Icm Architect

Restructure mode

1. Inventory before touching. List the tree. For each area note: what it is, when last touched, what refers to it. Never delete or move in this pass.

2. Find the hidden form. Ask the owner (or infer and confirm): what is the repeating unit here? Where does work enter and leave? The mess usually contains a real pipeline, library, or map that grew without a skeleton — extract it, don't replace it. Interview the folder the way you'd interview the person.

3. Classify every file into one of five roles:

• Catalog — identity/routing (becomes or feeds CLAUDE.md / index files)
• Contract — describes how a step works (becomes a CONTEXT.md)
• Factory — stable reference (→ _shared/, _system/, or references/)
• Product — run-specific artifacts (→ stage output/ or record folders)
• Dead — stale, duplicated, or superseded (→ propose _archive/, never silently delete). A file is Dead only after step 4 confirms nothing depends on it — apparent disuse is not proof.

4. Verify reference integrity — before proposing. Apparent disuse is not proof of safety. Before any file is proposed for a move — especially a Dead → _archive/ move — enumerate what points at it: in-vault, sibling-path (../), symlink, and outside this workspace (other repos, configs, scheduled jobs that hardcode a path in). External consumers are a question for the human gate, not an unbounded grep. A file with a live referrer is held, or moved only if every referrer is updated in the same change. See references/reference-integrity.md.

5. Propose before moving. Present the target tree and a migration map (old path → new path → role → referrers found). Get approval. This is a human gate in a method built on human gates — honor it. The reviewer approves against the reference report from step 4, not against a hunch.

6. Migrate — copy, verify, then remove. Never move-and-hope. Before any copy or rename, check whether the destination already exists case-folded — on Windows and macOS, CLAUDE.md → CONTEXT.md silently overwrites an existing context.md, and a file-inventory map will not show the collision. Surface every hit at the approval gate. Then copy to the new home, verify parity (file count and content hash) against the source, and only then remove the original. Write the entry file and contracts, de-duplicate toward one-home-per-fact (leave a link where the copy lived if anything referenced it). Separate method from instance: if the structure will be reused elsewhere, the blank template lives apart from this filled-in deployment.

7. Validate with the walk test.

The walk test

Validate any ICM — new or restructured — by walking it cold, as an agent with no memory:

• Open the root. Can you answer where am I and where do I go for the current task within the entry file plus at most two more reads?
• Pick any stage/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.
• After a restructure: does every reference that existed before the move still resolve? A moved file that something still points at is a break, not a tidy-up.
• Token check: entry file + one contract + its inputs should land in roughly 2k–8k tokens.
• System map only: can a cold agent answer what is X and what else moves if I change X from map/CLAUDE.md plus one card? Extra checks are in references/system-map.md.

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

Guardrails

• Don't over-structure. The ladder runs: chat → saved prompt/skill → folders + one agent. Only climb when the rung below is genuinely automated and repeating. A workspace for a thing done twice is scaffolding, not architecture.
• Know where ICM loses. Real-time multi-agent collaboration, high-concurrency multi-user serving, and automated mid-pipeline branching genuinely need framework code. ICM is for sequential, human-reviewed, repeatable work — which is most knowledge work, but not all of it.
• Anti-patterns seen in the wild: duplicated entry files that drift (generate one from the other, or make one a pointer); schema documents that mandate names the actual files stopped using (update the schema or the files — pick one); hand-edits to generated indexes; workshop sessions that produce slides instead of structured data (every working session should end in an artifact the structure can hold); patterns declared top-down (one team complaining is a gripe — the same shape appearing three independent times is structure).

References

• references/core.md — the five design principles, the five-layer context hierarchy, naming conventions, token discipline. Read when writing contracts or when a structural call is contested.
• references/forms.md — the six forms in depth: skeletons, moves, failure modes. Read at step 2 of Build mode or step 2 of Restructure mode.
• references/system-map.md — audit pipeline for the System map form. Read when that form is chosen.
• references/reference-integrity.md — the move-safety gate: what points at a file, case-folded destinations, copy-verify-remove. Read at step 4 of Restructure mode, or any time a move is contested.
• assets/templates/ — copyable starters: CLAUDE.md, workspace CONTEXT.md, stage-CONTEXT.md, node.md, object.md, process.md, schema.md, questionnaire.md.