icm-universal/SKILL.md

---
name: icm-architect-universal
description: "Design or restructure repeatable processes, ideas, knowledge bases, repositories, and vaults into ICM workspaces whose folder structure guides any coding agent through AGENTS.md conventions. Use for workspace building, agent-oriented organization, context maps, pipelines, or requests to 'ICM this'."
version: 1.0.0
author: RinDig / adapted for Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [icm, workspace-architecture, agents-md, opencode, knowledge-management, folder-structure]
    related_skills: [opencode, repository-onboarding-guide, plan]
---

# ICM Architect Universal

## Overview of ICM methodology

ICM (Interpretable Context Methodology) designs workspaces where the folder structure does the orchestration. Numbered folders carry sequencing, hierarchy carries context scoping, and plain text files carry state. One LLM agent, reading the right files at the right moment, can perform work that might otherwise require a multi-agent framework. A human can open any folder and see exactly what state the system is in because state is just files.

Think of the workspace as a library. Small, stable routing files are the catalog: they point at everything and store almost nothing. Content lives on the shelves (stage folders, node files, and reference material). One librarian — any coding agent — walks the building, and the question or task determines which shelf gets walked to. Nobody photocopies the library into a backpack; that is context-stuffing. The catalog is small on purpose.

ICM is model-agnostic by design. This skill uses `AGENTS.md` as the portable entry-file convention and works with OpenCode, Cursor, Windsurf, Codex, Hermes, or any other coding agent that reads AGENTS.md instructions. ICM is described in *Interpretable Context Methodology: Folder Structure as Agent Architecture* (Van Clief & McDermott, arXiv:2603.16021) and is MIT-licensed.

Use this skill to build a workspace from a described process, problem, or body of knowledge, or to restructure an existing folder, repository, or vault into an ICM workspace.

## The 10 invariants

Every ICM, whatever its form, obeys these. When building or restructuring, enforce all ten:

1. **One folder, one job.** 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. Target under ~60 lines. It routes; it never holds content.
3. **Numbering encodes order.** `01_`, `02_`, … where sequence matters. Renaming folders reorders the pipeline — that is the point.
4. **Every folder-level contract is explicit.** A `CONTEXT.md` per working folder: what it reads (inputs), what it does (process), what it writes (outputs), what a human checks.
5. **Factory vs. product.** Reference material (rules, voice, schemas, templates — stable across runs) lives structurally apart from working artifacts (outputs, drafts — new every run). Configure the factory once; the product is what each run emits.
6. **Every output is an edit surface.** Intermediate outputs are plain files a human can open, edit, and save before the next step reads them. Nothing moves forward until a person has read the last output.
7. **Load only what the step needs.** An agent executing a step reads its contract, its references, and its inputs — not the whole workspace. 2,000–8,000 tokens per step is the healthy range.
8. **Plain text, linkable, queryable.** Markdown + YAML frontmatter. Links (`[[wikilinks]]` or relative paths) make it a graph; frontmatter labels make it queryable. One home per fact — a link beats a copy.
9. **The filesystem is the state machine.** "Status" is derivable by scanning what exists in output folders. Generated indexes (file maps, logs) are rebuilt by script, never hand-edited.
10. **Instantiate by copying.** New unit of work = copy a template folder, not a blank page. Keep templates in a `_templates/` or `_system/` folder.

## Choose a mode

- **Building from a described process, idea, or problem** → **Build mode**.
- **An existing folder, repo, or vault that needs ICM structure** → **Restructure mode**.

## Build mode

### 1. Extract the structure from dialogue

Surface the structure already present in how the person describes the work; do not impose a shape. Ask a few questions at a time:

- What is the repeating unit of work (episode, client, report, person, or team)?
- Walk through one run from start to finish. Where do you stop and check something before continuing?
- What stays the same every run (voice, rules, brand, schema) versus what is new every run?
- What does “done” look like? What artifact leaves the workspace?
- Who else touches this, and what must they find without asking?

Pauses become stage boundaries, “I always check X before Y” becomes a human gate, and stable rules become factory reference material. Completion criterion: the repeating unit, sequence, human gates, stable factory, and final product are explicit.

### 2. Pick the form

Choose one of the five forms below. Forms can compose and recurse; the invariants still apply at every level. Completion criterion: name the selected form and explain why it fits the unit, flow, and output.

| Form | Reach for it when |
|---|---|
| **Pipeline** | The same sequence runs repeatedly, producing a deliverable each run |
| **Umbrella** | Several distinct pipelines share one brand, voice, or reference layer |
| **Record library** | The unit is a record (person, client, or session) that accumulates, not a run |
| **Knowledge bundle** | The product is navigable knowledge itself (a brain, wiki, or model) |
| **Context map** | The subject is an organization — teams, processes, data, and links between them |

### 3. Scaffold the smallest structure that carries the work

Copy starters from a `_templates/` or `_system/` folder and fill them in. Do not create speculative stages, empty “misc” buckets, or imagined depth. Three real stages beat seven imagined ones. If the whole job fits in one saved prompt, say so and do not build a workspace. Completion criterion: every created folder has one clear job and a useful artifact can enter the first real step.

### 4. Write the contracts

Write a root `AGENTS.md` with identity and routing, a root `CONTEXT.md` with the pipeline or schema definition, and one `CONTEXT.md` per stage or hub folder. Add `setup/questionnaire.md` when the factory needs per-user configuration. Give every contract explicit paths, distinguishing working inputs (this run) from reference inputs (every run). Completion criterion: an agent can execute each step from its contract without guessing paths or outputs.

### 5. Validate with the Walk Test

Run the Walk Test below before declaring the workspace complete. Completion criterion: every Walk Test question passes; fix structure rather than adding explanatory prose.

## Restructure mode

### 1. Inventory before touching

List the tree. For each area, note what it is, when it was last touched, and what refers to it. Do not delete or move files during this pass. Completion criterion: every existing file and folder is accounted for.

### 2. Find the hidden form

Ask the owner, or infer and confirm: what is the repeating unit? Where does work enter and leave? The mess usually contains a real pipeline, library, or map that grew without a skeleton — extract it rather than replacing it. Completion criterion: the target form, entry point, exit point, and major boundaries are confirmed.

### 3. Classify every file

Assign every file one role:

- **Catalog** — identity and routing; becomes or feeds `AGENTS.md` or an index.
- **Contract** — describes how a step works; becomes a `CONTEXT.md`.
- **Factory** — stable reference; moves to `_shared/`, `_system/`, or `references/`.
- **Product** — run-specific artifact; moves to a stage `output/` or record folder.
- **Dead** — stale, duplicated, or superseded; propose `_archive/`, never silently delete.

Completion criterion: no file is unclassified and each proposed destination has a reason.

### 4. Propose before moving

Present the target tree and a migration map (`old path → new path → role`) and get human approval. This is a human gate in a method built on human gates; honor it. Completion criterion: approval is explicit before any move or deletion.

### 5. Migrate

Move files, write the entry file and contracts, and de-duplicate toward one home per fact. Leave a link where the old copy lived if anything might reference it. Keep reusable blank templates apart from the filled-in deployment. Completion criterion: every source file has a destination, preserved link, or approved archive disposition.

### 6. Validate with the Walk Test

Walk the migrated workspace cold as an agent with no memory. Completion criterion: all Walk Test checks pass and the migration map matches the resulting tree.

## The Walk Test

Validate any ICM — new or restructured — by walking it cold:

- Open the root. Can you answer **where am I** and **where do I go for the current task** within `AGENTS.md` plus at most two more reads?
- Pick any stage or node. Does its contract name exact input paths, the job, the output, and the human check?
- Can you state pipeline status purely by scanning what exists in `output/` folders (or node frontmatter)?
- Is any routing file carrying content payload? Move the payload to a shelf; leave a pointer.
- Is any fact stored in two places? Pick one home; link from the other.
- **Token check:** entry file + one contract + its inputs should land in roughly 2k–8k tokens.

If a check fails, fix the structure — not by explaining more, but by moving or splitting files until the walk works.

## The 5 Forms reference

### Pipeline
A repeatable production line with numbered stages and human approval between outputs.

```text
workspace/AGENTS.md  CONTEXT.md
stages/01_research/{CONTEXT.md,references/,output/}
stages/02_draft/{CONTEXT.md,references/,output/}
_shared/  _templates/  setup/questionnaire.md
```

### Umbrella
A portfolio of distinct pipelines sharing a common factory layer.

```text
workspace/AGENTS.md  01-pillars/  02-brand-voice/
03-video-production/ (full Pipeline)
04-scene-generation/ (full Pipeline)
05-animation-studio/ (full Pipeline)
```

### Record Library
A collection of accumulating records, with templates and an index.

```text
workspace/00_START-HERE.md  _index/log.md
_templates/record-template/  01_reference/
records/acme-corp/  records/jane-doe/
```

For universal agent routing, add or pair the start file with root `AGENTS.md`.

### Knowledge Bundle
A navigable body of knowledge with a factory pipeline for extraction and structured output bundles.

```text
workspace/AGENTS.md  corpus/  extraction/ (factory Pipeline)
bundle/index.md  voice/  dispositions/  episodes/
```

### Context Map
An organization or system represented as linked context nodes, patterns, and dashboards.

```text
workspace/AGENTS.md  FILE-MAP.md  _meta/schema.md
teams/marketing/Marketing.md  patterns/  dashboards/
```

Forms compose freely: a record library may contain mini knowledge bundles, and a pipeline may emit into a record library.

## Guardrails / anti-patterns

- **Do not over-structure.** Use the ladder: chat → saved prompt or skill → folders plus one agent. Only climb when the lower rung is genuinely automated and repeating. A workspace for a thing done twice is scaffolding, not architecture.
- Keep the entry file small and stable. Do not duplicate routing files; if compatibility requires another index, make one the pointer to the other.
- Do not create speculative stages, empty “misc” folders, or framework code where a contract and plain file suffice.
- Schema documents must match actual filenames and metadata. Update the schema or the files; do not allow drift.
- Never hand-edit generated indexes, file maps, or logs; rebuild them with their generator.
- A workshop, interview, or agent session must end in a structured artifact the workspace can hold, not only slides or conversation.
- Do not declare a pattern from one complaint. Repeated structure appearing independently is stronger evidence.
- Preserve human gates: no output moves forward until a person has read and, when appropriate, edited or approved it.

## Where ICM loses (honest limitations)

ICM is strongest for sequential, human-reviewed, repeatable knowledge work. It is not a universal replacement for orchestration or application architecture. Use framework code or a database when you need real-time multi-agent collaboration, high-concurrency multi-user serving, transactional guarantees, complex automated mid-pipeline branching, low-latency event handling, or strict access-control enforcement. Filesystem-derived state can be slower, less atomic, and more conflict-prone than purpose-built infrastructure. A model-agnostic folder method also cannot guarantee that every LLM agent interprets instructions identically; verify behavior with the Walk Test and project-specific checks.

## Setup questionnaire template

Copy this into `setup/questionnaire.md` and answer it before configuring a reusable factory:

```markdown
# ICM setup questionnaire

## Identity
- Workspace name:
- One-sentence purpose:
- Owner and collaborators:
- Which coding agents must support it (OpenCode, Cursor, Windsurf, other):

## Repeating work
- What is the repeating unit (run, record, node, or bundle):
- Walk through one complete run:
- Where are the human review/approval gates:
- What artifact proves “done”:

## Factory vs. product
- Stable rules, voice, schemas, and templates:
- New inputs and outputs per run:
- What must never be duplicated:

## Routing and contracts
- First task an agent should support:
- Required entry file location (root `AGENTS.md`):
- Stages, hubs, or node types:
- Inputs and exact paths for each:
- Outputs and exact paths for each:
- Human check for each output:

## Operations
- How is status derived from files:
- Which indexes are generated and by what command:
- Naming and frontmatter conventions:
- Archive/retention policy:
- What should remain deliberately outside this workspace:
```

## Minimal contract and entry templates

### Stage contract (`CONTEXT.md`)

```markdown
# NN_stage-name — the job in five words
One job: the single thing this stage does.

## Inputs
- Working (this run): ../NN-1_prev-stage/output/file.md
- Reference (every run): ../../_shared/rules.md
- Do NOT load: other stages’ references, prior runs, or the whole workspace.

## Process
1. Read the inputs.
2. Transform them.
3. Enforce hard limits and record uncertainties.

## Outputs
- artifact.md → output/

## Human check
One concrete act: read and edit or approve `output/artifact.md` in place.
```

### Entry file (`AGENTS.md`)

```markdown
# Workspace name
One sentence. Built on ICM.

## Where things live
| Folder | What it holds |
|---|---|
| stages/ | pipeline in execution order |
| _shared/ | factory rules |
| _templates/ | blank starters |
| setup/ | one-time configuration |

## Route by what just happened
| If | Go to | Then stop at |
|---|---|---|
| starting new run | stages/01_.../CONTEXT.md | human reads output |
| previous stage approved | next numbered stage | human reads output |
| asked for status | scan stages/*/output/ | report what exists |
| setting up new user | setup/questionnaire.md | answers → _shared/ |

## The one rule
Nothing moves to the next stage until a person has read the output of the last one.
```

## Verification checklist

Before finishing an ICM build or restructure:

- [ ] The root uses `AGENTS.md` as its entry convention.
- [ ] All ten invariants are satisfied or an explicit exception is documented.
- [ ] The selected form matches the actual repeating unit and output.
- [ ] Every working folder has a `CONTEXT.md` contract.
- [ ] Factory references are separated from products and drafts.
- [ ] Outputs are plain, human-editable files.
- [ ] Status is derivable from files rather than prose or hidden state.
- [ ] The Walk Test passes, including the 2k–8k token check.
- [ ] No generated index is hand-edited and no fact has two competing homes.