icm-architect
Claude skill: design any process, idea, or problem into an ICM workspace (folder structure as agent architecture), or restructure an existing folder into one
What is it?
What it is
A Claude skill that designs processes, ideas, or problems into an ICM (Interpretable Context Methodology) workspace — using folder structure as agent architecture — or restructures existing folders, repos, or vaults into one. It scaffolds workspaces based on six proven forms (Pipeline, Umbrella, Record library, Knowledge bundle, Context map, System map) and validates results with a walk test ensuring an agent with no memory can orient, act, and report status from files alone.
Why it exists
To replace orchestration code with interpretable structure. ICM enables one agent to do the work of a multi-agent framework by encoding sequencing in numbered folders, context scoping in hierarchy, and state in plain markdown files. It makes system state visible to humans and navigable by agents without requiring complex routing logic or hidden state.
Who should use it
AI engineers, LLM developers, and researchers interested in building structured agent workflows using the ICM methodology.
Who should avoid it
Users who do not use Claude Code, prefer traditional orchestration, or are uncomfortable with markdown-based folder structures.
How it works
A quick walkthrough in plain English
How icm-architect works
Step 1 of 3
You interact with it
Open icm-architect, send a request, or connect it to your stack.
Features
Advantages
- Replaces complex orchestration code with simple, interpretable folder structure
- Enables a single agent to perform the work of a multi-agent framework
- Human-readable and inspectable: anyone can open a folder and understand system state
- Validated by the walk test, ensuring reliability and orientation for agents
- MIT licensed, promoting open use and modification
- Compositional and recursive forms allow scaling from simple to complex workflows
- Smallest viable workspace scaffolding reduces unnecessary complexity
- Migration map approval step provides safety and control when restructuring existing projects
- Templates and reference materials accelerate adoption and consistent implementation
- Supports both greenfield design (Build) and legacy refactoring (Restructure)
Disadvantages
- Requires learning the ICM methodology and its five principles before effective use
- Limited to Claude ecosystem (Claude Code and Claude apps), restricting platform portability
- Folder-based state management may not suit all types of dynamic or real-time processes
- Walk test validation adds overhead and may slow down rapid iteration cycles
- Restructure mode depends on accurate file classification, which may require manual review
- Six forms, while composable, may initially overwhelm users unfamiliar with the framework
- No built-in support for non-markdown or binary file types in state representation
- Single-agent model may become a bottleneck for highly parallelizable tasks
- Migration of large repositories could be time-consuming and error-prone without careful planning
- Lack of automated tooling beyond the skill itself; relies heavily on manual folder and file management
Installation
FAQ
What is ICM-architect and what does it do?
ICM-architect is a Claude skill that transforms processes, ideas, or problems into an ICM workspace — a folder structure designed as agent architecture. It supports two modes: Build (scaffolding new workspaces from existing structures) and Restructure (auditing and migrating existing folders into ICM-compliant structures). It uses six forms: Pipeline, Umbrella, Record library, Knowledge bundle, Context map, and System map.
How do I install ICM-architect for use with Claude Code?
Copy the icm-architect folder to ~/.claude/skills/icm-architect/ (or inside a project's .claude/skills/ directory). Once installed, you can invoke it by asking Claude to 'ICM this', 'structure this for agents', or 'build me a workspace for X'.
What are the six forms supported by ICM-architect?
The six forms are: Pipeline (production line), Umbrella (portfolio of pipelines), Record library (people/clients/sessions), Knowledge bundle (navigable brain), Context map (organization as a graph), and System map (folder for agent-editable nouns, movements, and change-impact). These forms can compose and recurse.
How does the Build mode work?
Build mode extracts the structure already present in how you describe your work (stages, human gates, stable vs. per-run elements), selects one of the six proven forms, and scaffolds the smallest workspace that carries it. The result is validated using the walk test to ensure an agent can orient, act, and report status from the files alone.
What is the Restructure mode and how does it validate changes?
Restructure mode audits an existing folder, classifies every file into categories (catalog, contract, factory, product, dead), proposes a migration map for approval, then migrates and validates the changes. Validation ensures the restructured workspace passes the walk test for agent usability.
What is the walk test and why is it important?
The walk test is a validation method where an agent with no memory must orient, act, and report status from the files alone. It ensures the workspace is interpretable and functional for both human and agent interaction, confirming that the structure carries context and sequencing effectively.
Featured in Videos
YouTube tutorials and walkthroughs for icm-architect
Alternatives
Similar projects ranked by category, topics, and text overlap.
