---
id: "framework-icm-architecture"
type: "framework"
source_timestamps: ["§3.2", "Figure 2"]
tags: ["architecture", "folder-structure", "reference"]
related: ["concept-icm", "concept-five-layer-hierarchy", "concept-stage-contracts"]
sources: ["paper"]
sourceVaultSlug: "icm-paper-folder-architecture-2026Jun02"
originDay: 2
---
# ICM Workspace Architecture

## Canonical on-disk layout

The canonical structure, every node annotated by layer from [[concept-five-layer-hierarchy]]:

```
workspace/
├── CLAUDE.md                    # Layer 0: global identity
├── CONTEXT.md                   # Layer 1: workspace routing
├── _config/                     # Layer 3: cross-stage reference
├── shared/                      # Layer 3: voice, design system, conventions
├── setup/
│   └── questionnaire.md         # un-layered: runs once at creation
└── stages/
    ├── 01_research/
    │   ├── CONTEXT.md           # Layer 2: stage contract
    │   ├── references/          # Layer 3: stage-local references
    │   └── output/              # Layer 4: working artifacts
    ├── 02_script/
    │   ├── CONTEXT.md
    │   ├── references/
    │   └── output/
    └── 03_production/
        ├── CONTEXT.md
        ├── references/
        └── output/
```

## Construction steps

1. **workspace/** root holds `CLAUDE.md` (L0 identity) and `CONTEXT.md` (L1 routing).
2. **stages/** contains numbered stage folders (`01_research`, `02_script`, `03_production`).
3. **Each stage folder** holds `CONTEXT.md` (L2 contract), `references/` (L3), `output/` (L4).
4. **_config/** and **shared/** hold cross-stage L3 reference (voice, design system, conventions).
5. **setup/** holds a questionnaire run once at workspace creation.
6. **The same agent** runs each stage; folder scoping controls its context; humans review at each `output/` boundary — see [[concept-stage-contracts]].

## Why the repeating triad matters

Every stage folder is the same triad — `CONTEXT.md` (L2) + `references/` (L3) + `output/` (L4) — which is what makes **"add or remove a stage" a filesystem operation**, not a code change. Implemented as [[action-numbered-stage-folders]] and [[action-separate-l3-l4]].

Top-level `_config/` and `shared/` hold L3 material shared across stages without duplication. `setup/questionnaire.md` is un-layered: it runs once at creation and is the seam where non-coder onboarding happens — exploited by [[framework-workspace-builder]].

## Dual role

The repeating, inspectable structure is **both** the human control surface and the agent's orchestration specification. This is the thesis captured in [[quote-folder-controls-context]].


## Related across days
- [[action-implement-folders]]
- [[concept-icm-d1]]
- [[concept-five-layer-hierarchy]]
- [[synthesis-five-layer-fills-the-gap]]
- [[concept-portability]]