icm

ICM — Interpretable Context Methodology

Folder-as-architecture for AI agents. Replaces multi-agent frameworks with a 5-layer filesystem contract any agent can read, navigate, and extend safely.

A deliberately thin Claude Code plugin:

• 🛡️ One guardrail skill (icm) — auto-loads on entering an ICM workspace; carries how to detect ICM + the base rules, and points to the canon (loaded on demand, never inlined).
• 🤝 One primitive (dispatch-subagent) — spawn a subagent that enters as a generic ICM agent and self-routes to a room (worker mode) or runs an auto-review pre-pass (reviewer mode). Model scales by tier.
• ⌨️ Two commands — /icm:new (create a workspace / department / room / sub-room) and /icm:assimilate (audit / convert), each a front-door to a maintenance room.
• 🏗️ A canonical maintenance dept (templates/maintenance/) scaffolded into every workspace — modify-workspace (create + structural change), modify-room (cheap in-convention edits), janitor (file hygiene + pointer rewiring), audit (read-only conformance + memory). New capability is always a room, never a new command.
• 🔧 A per-room tooling model (tools.json) — tools live in a central .claude/ store, disabled by default, activated per room by path. Cost tiers in one editable model-tiers.md table.
• 🐍 One stdlib checker (scripts/icm_check.py) — enforces the Invariants; /icm:assimilate runs it.
• 📜 Methodology docs (docs/: LAYERS, CONVENTIONS, ROOM-CONTRACT, ROUTING) as the source of truth.
• 🧪 Tests that run the checker against a demo workspace + temp fixtures.

Inspired by the ICM paper and the original Interpreted-Context-Methodology repo.

What is ICM?

Most "AI agents" are prompts + orchestration code that sequence a single model through a workflow. ICM replaces that scaffolding with folders and markdown. The folder structure IS the orchestration: one agent navigates it, loading only the context relevant to the current step. No frameworks, no DAGs.

The five layers

Layer	File	Job
0	AGENTS.md (+ stubs CLAUDE.md/GEMINI.md/.cursorrules)	What this place is + how to enter + base rules
1	root CONTEXT.md	Maps + routing (where to go)
2	each dept/room/sub-room CONTEXT.md	The contract
3	each docs/	Stable rules + memory — read-only during a run
4	projects/<run>/... or room-local workbench-<id>/	Per-run artifacts — the only write target

Full detail: docs/LAYERS.md. A workspace can be flat or clustered into departments, and a room can nest sub-rooms (recursion by need).

Install (Claude Code)

/plugin install https://github.com/pinguinzz/ICM-Plugin

Registers two skills (icm, dispatch-subagent) and two commands (/icm:new, /icm:assimilate).

Skills

Skill	Purpose
icm	Guardrail meta-skill — auto-loads on entering an ICM workspace. How to detect ICM, the base rules (incl. in-place room evolution), nested-ICM detection, and pointers to the commands + canon. The canon is loaded on demand, not inlined.
dispatch-subagent	Spawn a subagent that enters as a generic ICM agent and self-routes. Worker (do real work in a room, e.g. a gated edit via the maintenance room) or reviewer (transitory auto-review pre-pass). Model scales to the work's value.

Commands

Command	What it does
/icm:new	Front-door to the modify-workspace room. Create new structure — workspace, department, room, or sub-room. Backbone-locked intake; scaffolds from templates/ (incl. the maintenance dept on a new workspace). Additive only.
/icm:assimilate	Front-door to the audit room. Read-only, plan-mode. Convert a non-ICM folder (emits a conversion plan) or integrity-check an ICM one (grills, runs icm_check.py, suppresses acknowledged exceptions, reports, emits a fix plan routed to the maintenance rooms). Never mutates.

Both are also reachable through the skill base as /icm -new / /icm -assimilate. Each command is one procedure reachable two ways — native slash command + skill-base dispatch.

Use it without Claude Code

# Check any workspace against the Invariants
python scripts/icm_check.py /path/to/workspace            # human-readable
python scripts/icm_check.py /path/to/workspace --json     # machine-readable
python scripts/icm_check.py /path/to/workspace --strict   # warnings fail too

The templates and docs are plain files any AGENTS.md-aware agent can use.

Repo layout