/icm-architect

name: icm-architect
description: Design a process, idea or body of knowledge into an ICM (Interpretable Context Methodology) workspace, where folder structure is the agent architecture, or restructure an existing folder, repo or vault into one. Use for "make this an ICM", "ICM this", "build me a workspace", "structure this for agents", "map this repo", "audit this folder", "what would a change hit", a second brain, team brain or context map, or turning transcripts and research into material for lectures, scripts or docs.
license: MIT

ICM Architect

Build workspaces where the folder structure does the orchestration. One agent, reading the right files at the right moment, replaces a multi-agent framework: numbered folders carry sequencing, hierarchy carries context scoping, plain markdown files carry state. A person can open any folder and see what state the system is in, because state is just files. The routing files are the catalog: small and stable, they point at the shelves where the content lives.

Method: Interpretable Context Methodology (Van Clief & McDermott, arXiv:2603.16021, MIT-licensed). It runs in any agent or model that can read files: nothing in a workspace depends on one vendor's tools.

The invariants

Every ICM starts from these ten. They are defaults: when you know what works and need a nuanced change, break one on purpose and write why in the nearest `CONTEXT.md` or `AGENTS.md`.

1. **One folder, one job** (Unix, Parnas). Each folder does a single step or holds a single kind of thing, and states its own purpose in a file inside itself. The structure is the documentation. 2. **A small, stable entry file.** `AGENTS.md` at the root answers "where am I, where does everything live, where do I go for task X" and nothing else. Under ~60 lines; it routes and never holds content. A tool that looks for another file name gets a one-line pointer to it, never a second copy (see [references/core.md](references/core.md), Naming). 3. **Numbering encodes order.** `01_`, `02_`, ... where sequence matters. 4. **Every working folder has a contract.** A `CONTEXT.md`: what it reads (inputs), what it does (process), what it writes (outputs), how it is checked. See [assets/templates/stage-CONTEXT.md](assets/templates/stage-CONTEXT.md). 5. **Factory vs. product** (continuous delivery). Reference material (rules, voice, schemas, templates: stable across runs) lives apart from working artifacts (outputs, drafts: new every run), because they ask different things of the model: references constrain, inputs are worked on. Configure the factory once; the product is what each run emits. 6. **Every step ends at a check** (Horvitz, Shneiderman). Each output is a plain file a person can open, edit and save. Nothing moves on until it passes the check its stage names under `## Check`: a person, a script, or a small model. A check that isn't a person writes `check.md` beside the output, first line `pass` or `fail: <why>`; a fail stops the run there. The stop is the point: a wrong turn caught here is not amplified downstream. 7. **Load only what the step needs.** A step reads its contract, its references and its inputs, never the whole workspace: under about 8,000 tokens. Prevent, don't compress. 8. **Plain text, linkable, queryable** (Kernighan, Pike). Markdown + YAML frontmatter. Links make it a graph; frontmatter labels make it queryable. One home per fact; a link beats a copy. Links and input paths are relative and must resolve; wikilinks only in a declared Obsidian vault. The first heading names the file and its job, so `grep -rm1 '^# ' .` lists any tree. 9. **Status lives on disk:** what exists, or one status line in the file it describes. Generated indexes (`_index.md`, file maps) are rebuilt by script, never hand-edited. 10. **Instantiate by copying.** A new unit of work is a copy of a template, not a blank page. Templates live in `_templates/`, scripts in `_tools/`.

Choose a mode

• **Build**: from a described process, idea, or problem.
• **Restructure**: an existing folder, repo, or vault that needs ICM structure.

Some forms bring their own pipeline (System map; Knowledge bundle from sources). Their reference says which steps it replaces.

Three primitives

Every ICM is built from three things:

• **Sequence**: numbered folders; each step's `output/` is the next step's input.
• **Shelf**: a folder of same-shaped files, each copied from one template.
• **Catalog**: a small file that points down and stores no content: `AGENTS.md`, a `CONTEXT.md`, a generated index or graph.

The forms below are recipes over these. Nest them freely; each level keeps its own small catalog that links down and stops. An Umbrella is one catalog over several pipelines, with their shared shelf at the root. When no form fits, build from the three and name the recipe in the entry file.

Build mode

**1. Extract the structure from dialogue.** The structure is already in how the person describes the work: surface theirs, don't impose one. Ask, a few at a time:

• What is the repeating unit of work? (an episode, a client, a report, a person, a team?)
• Walk me through one run, start to finish. Where do you stop and check something before continuing?
• What stays the same every run (voice, rules, brand, schema) vs. what is new every run?
• What does "done" look like: what artifact leaves the workspace?
• Who else touches this, and what do they need to find without asking you?

Their pauses become stage boundaries. Their "I always check X before Y" become checks. Their "it always has to sound like / follow Z" becomes factory reference material.

**2. Pick the form.** Read [references/forms.md](references/forms.md) and choose:

| Form | Built from | Reach for it when | |---|---|---| | **Pipeline** | a sequence | the same steps run again, a deliverable each run | | **Record library** | a shelf of records with a status line each | the unit is a record that accumulates (person, client, session) | | **Knowledge