RinDig/icm-architect: a Claude skill that turns folder structure into agent architecture

What problem icm-architect solves, and for whom

Multi-agent frameworks put the coordination in code. A supervisor routes, a queue retries, a state store serialises. The README states that ICM (Interpretable Context Methodology) replaces that orchestration code with structure: numbered folders carry sequencing, hierarchy carries context scoping, and plain markdown files carry state. The claim attached to it is specific: one agent, reading the right files at the right moment, does the work of a multi-agent framework, and a human can open any folder and see what state the system is in.

The audience follows from that claim. If you are debugging an agent pipeline and cannot tell from the outside which stage is stuck, the folder tree is meant to answer that question without a dashboard. If you are handing a process to someone else, the tree is the handover document. The README frames the workspace as a library and the routing files as the catalog: small, stable, pointing at everything and storing almost nothing, with one librarian walking the building and the question deciding which shelf gets walked to.

It is not for people who want a library to import. There is no package, no server, no CLI in the layout. The repository is SKILL.md, four reference files, and a templates folder. The product is a set of instructions that Claude applies to your filesystem.

Build mode and restructure mode: two ways in

The skill has two modes and they do different work.

Build mode extracts the structure already present in how you describe your work: the stages, the human gates, what is stable versus what is per-run. It then picks one of six forms and scaffolds the smallest workspace that carries that structure. The six forms share one skeleton. Pipeline is a production line. Umbrella is a portfolio of pipelines. Record library holds people, clients or sessions. Knowledge bundle is a navigable brain. Context map treats an organisation as a graph. System map produces a folder that later agents will edit, organised around nouns, movements and change impact. The README says the forms compose and recurse.

Restructure mode starts from what you already have. It audits an existing folder, repo or vault, classifies every file as catalog, contract, factory, product or dead, proposes a migration map for approval, then migrates and validates. The approval step matters: the classification is a judgement about your files, and the reference file reference-integrity.md is described as the move-safety gate for that stage.

Both modes end at the same check. The walk test asks whether an agent with no memory can orient, act, and report status from the files alone. That is the acceptance criterion the README names, and it is the one worth arguing about, because it is qualitative. Nothing in the repository as described automates the walk test; a person or a model has to attempt the walk and judge the result.

Installing the icm-architect skill in Claude Code

Claude Code loads skills from a skills directory, and the README gives the path. Copy the icm-architect folder into your user-level skills directory to make it available across projects:

cp -r icm-architect ~/.claude/skills/icm-architect/

The alternative is a project-scoped install, which keeps the skill with the repository it serves. The README gives that path as `.claude/skills/icm-architect/` inside a project. Use the project path when the workspace being designed belongs to one codebase and you do not want the skill appearing in unrelated sessions.

For the Claude apps rather than Claude Code, the README describes uploading a packaged file. The archive is named `icm-architect.skill`, and it can be produced with the skill-creator packager or by zipping the folder yourself. The packaging detail the README calls out is that the folder is the zip root, not its contents:

zip -r icm-architect.skill icm-architect/

Upload the result through Customize then Skills. If the archive is built from the contents instead of the folder, the structure the skill expects will not be at the root when it is unpacked.

A first real use: asking Claude to ICM a process

After installation, the skill is invoked in conversation rather than from a terminal. The README lists the phrasings it responds to: "ICM this", "structure this for agents", and "build me a workspace for X".

A first run is best done on a process you can describe in a few sentences, including where a human has to approve something. Describe the stages, say which artefacts are stable across runs and which are produced per run, and name the points where you want a person to look before work continues. Build mode is documented as extracting exactly those elements, so a description without gates will produce a workspace without gates.

What you should expect to see is a numbered folder tree plus routing files. The templates folder in the repository shows the shapes involved: a CLAUDE.md, a CONTEXT.md, a stage contract, a node card, object and process cards, a schema, and a questionnaire. Those are described as copyable starters, so the fastest way to understand the output is to open assets/templates/ and compare a stage contract against the stage folders the skill produced for you.

If you would rather start from existing material, run restructure mode on a folder you already work in. The output to review is the migration map, which arrives before any files move.

Where the method breaks down

The honest limitation is the one the README implies rather than states. Structure carries sequencing, so the sequencing is only as good as the numbering and naming conventions, and those are conventions, not enforcement. A folder named 03_review does not stop anything from running 04 first. The README's walk test is designed to catch the resulting confusion, but the walk test is a manual check performed after the fact.

There is a second boundary. The reference file reference-integrity.md is described as a move-safety gate for restructuring, which tells you the authors expect moves to be risky. Restructuring a live repository means the classification of every file as catalog, contract, factory, product or dead is a judgement call made by a model reading your tree. Files it labels dead are the ones you should look at hardest, and the README does not document rollback for the migration step.

Finally, this is the wrong tool when the work genuinely needs concurrency. A pipeline form serialises stages by folder order. If your process has independent branches that must run at the same time and reconcile, or if you need retries with backoff and a durable execution log, a folder tree gives you none of that. The method's bet is that most processes people reach for orchestration to solve are actually sequential with human gates, and that bet is wrong for some of them.

How this differs from a multi-agent framework

The nearest comparison is a multi-agent framework such as LangGraph or CrewAI, where you declare agents, tools and edges in code and a runtime executes the graph. The difference is not stylistic. In a framework, the control flow is executable: the runtime knows which node is active, can retry it, and can log the transition. In ICM as described here, the control flow is the folder numbering and the state is markdown that the agent reads. You gain inspectability, because any editor shows you the current state. You lose the runtime guarantees, because nothing is executing the structure except the model's reading of it.

A second comparison is a plain notes vault with a CLAUDE.md at the root. That is where many people already are. The difference icm-architect claims is the classification discipline and the forms. A vault accumulates; the skill sorts files into catalog, contract, factory, product and dead, and forces a choice among six named shapes with documented failure modes in references/forms.md. Whether that discipline is worth the restructuring depends on how much your current folder has drifted. If it has not drifted, the skill is overhead.

Maintenance, upgrade cost and licence

The repository is not archived, and the last push was on 2026-08-25. There are no releases, so there is no version number to pin and no changelog to read before upgrading. Updates arrive as commits to the default branch, and an upgrade means replacing the folder you copied into ~/.claude/skills/icm-architect/ or .claude/skills/icm-architect/ with the new one.

The cost of that upgrade is asymmetric. Replacing the skill is trivial. The workspaces it produced are yours, and they are plain folders and markdown, so they keep working regardless of what happens to the skill. The dependency runs one way: the skill needs Claude to run, the workspaces do not need the skill. That is a favourable property for anything you build with it, and it is the main reason the method is worth evaluating even if you never adopt the skill permanently.

The licence is MIT, the same licence the README says the protocol itself uses. In practical terms MIT permits commercial use and modification with the licence and copyright notice retained. This is not legal advice; if you are redistributing the skill inside a product, read LICENSE in the repository root rather than relying on this summary.

Editorial conclusion

Adopt icm-architect if you already run Claude Code or the Claude apps and you want a folder tree that a single agent can walk without orchestration code, and you accept that the sequencing lives in numbering conventions and human gates rather than in a scheduler. Do not adopt it if you need parallelism, retries, or a durable execution log: the method replaces those with structure, and the README describes no runtime that would restore them. Before committing, verify three things in the repository itself: that SKILL.md states the invariants and the walk test in enough detail to apply without the paper, that references/forms.md gives the failure mode for the form you intend to use, and that assets/templates/ contains a stage contract you can fill in for your own stages. The licence is MIT, so the practical question is not legal but editorial: whether the skill's rules survive contact with a folder you did not design.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. RinDig/icm-architect on GitHub