icm-walk 🚶‍♂️

Walk your workspace. Validate the invariants. Keep your agents oriented.

icm-walk is a CLI tool that evaluates workspaces against methodology invariants. It supports multiple evaluation modes via feature flags.

Install

npm install -g icm-walk

Or run directly:

npx icm-walk

Usage

# ICM Walk — validates ICM workspace structure
icm-walk [directory] --icm

# Cursor Evaluation — checks workspace readiness for Cursor/agent coding
icm-walk [directory] --cursor

# JSON output (works with any mode)
icm-walk [directory] --cursor --json

# Verbose
icm-walk -v

# Help
icm-walk --help

Evaluation Modes

--icm — ICM Walk (default)

Validates a directory against the Interpretable Context Methodology (ICM) invariants. Runs the walk test — an agent with no memory opens the workspace cold and verifies it can orient, act, and report from the files alone.

ICM (Van Clief & McDermott, arXiv:2603.16021) replaces orchestration code with folder structure: numbered folders carry sequencing, hierarchy carries context scoping, plain markdown files carry state.

| # | Invariant | What happens if it fails | |---|-----------|--------------------------| | 1 | Entry file exists (CLAUDE.md, AGENTS.md, or .hermes.md) | Agent can't orient — fails before starting | | 2 | Entry file under ~60 lines / ~800 tokens | Bloated routing = agent loses the map | | 3 | Routing files carry no content payload | Content in routing files = context-blown entry point | | 4 | Stage folders follow NN_kebab-name convention | Pipeline sequence is guesswork | | 5 | Each stage folder has a CONTEXT.md | Agent enters a folder blind | | 6 | CONTEXT.md has Inputs, Process, Outputs, Human check | Missing sections = agent makes up the workflow | | 7 | Inputs split working vs reference | Agent can't tell fresh data from ground truth | | 8 | Factory directories exist (references/, _shared/) | Stable knowledge mingles with per-run artifacts | | 9 | Output folders exist per stage | Products have no home — next stage can't find them | | 10 | Token estimate per stage in 200–8,000 range | Bloated stages blow context windows |

--cursor — Cursor Evaluation

Evaluates a workspace's readiness for Cursor/agent-based coding. Checks that your project is configured so an AI coding agent can work effectively.

| # | Check | What it looks for | |---|-------|-------------------| | 1 | .cursorrules | Exists, sized under 2,000 tokens, covers tech stack, code style, and testing | | 2 | .cursorignore | Present when generated dirs exist (node_modules, .venv, dist) | | 3 | Entry file | Sized for Cursor's context window (target < 800 tokens) | | 4 | Cursor hints | Entry file contains Cursor-specific guidance (optional) | | 5 | README | Has setup and usage sections — Cursor uses this as primary orientation | | 6 | .gitignore | Present — Cursor respects it to skip build artifacts | | 7 | Dependency manifest | package.json, pyproject.toml, or Cargo.toml found | | 8 | Tests | Test directory or test files exist | | 9 | File size distribution | Analyzes all source files, flags anything over 3,000 tokens | | 10 | tsconfig.json | Bonus check for TypeScript projects |

# Quick read on a project
icm-walk /path/to/project --cursor

# CI pipeline check
icm-walk /path/to/project --cursor --json | jq '.status'

Exit codes

• 0 — All checks pass. Workspace is healthy.
• 1 — Warnings only. Workspace works but has cleanup opportunities.
• 2 — Failures. Breaking invariants — fix before relying on this workspace.

Integrating with CI

# ICM mode CI check
icm-walk --icm --json | jq '.status'

# Cursor mode CI check
icm-walk --cursor --json | jq '.status'

License

MIT — see LICENSE.

Built with 🛸 by Zero for shift-zero