Back to ICM
Part 4 of 5 · Practitioner · 15 min

ICM in the Wild

Two real workspaces, walked end to end: what they look like, how they run, and the open convention that keeps them portable.

It's hard to describe what an ICM workspace feels like without showing one. The abstract version (folders, stages, routing tables, contracts) sounds like over-engineering until you open one and realize how small they are. A whole workspace is usually three or four screens of markdown across maybe a dozen files. You can read the entire thing in ten minutes. Compared to a Python codebase that does the same job, with chains, callbacks, custom types, and conditional routing logic, the workspace is two orders of magnitude shorter. So the rest of this part is two walkthroughs of real workspaces (one I run regularly, one slightly larger), with the actual file structure shown as it sits on disk.

The smaller one: meeting-summarizer

meeting-summarizer is a five-stage workspace that takes a meeting transcript and produces a structured summary. It's the simplest real workspace I have. The whole thing fits on one screen:

meeting-summarizer/
├── CLAUDE.md                              # workspace map
├── shared/
│   ├── large-transcript-handling.md       # precondition for stage 01
│   └── summarization-tips.md              # cross-stage voice guidance
└── stages/
    ├── 01-meeting-notes/                  # comprehensive notes
    ├── 02-action-items/                   # follow-ups
    ├── 03-key-insights/                   # discoveries beyond what was covered
    ├── 04-extended-notes/                 # GATED: only on explicit request
    └── 05-assemble-and-deliver/           # human pause: confirm folder before write

The top-level CLAUDE.md is the map. It tells the agent that this is a meeting-summarization workspace, that the input is a transcript path, that stages run 01 → 05 in order, that stage 04 is gated unless the user explicitly asks for extended notes, and that stage 05 pauses for human confirmation before writing the final file. About forty lines, under 800 tokens. The agent reads this when the workspace opens and never has to come back to it.

The shared/ folder holds the cross-stage references. large-transcript-handling.md is loaded only by stage 01 (the inputs table for that stage points at it specifically), and only if the transcript exceeds 100KB. Below that size, the agent skips it. summarization-tips.md is loaded by every stage that does generative work; it carries voice guidance that applies throughout. Two files, both tightly scoped. Neither lives inside any one stage because both apply across multiple.

Each stage folder contains a CONTEXT.md that follows the standard contract (Inputs, Process, Audit, Outputs) and an output/ subfolder where the stage's artifacts land. Stage 01 reads the transcript and writes notes.md. Stage 02 reads the transcript and notes.md, writes action-items.md. Stage 03 reads the transcript and notes.md, writes insights.md. The handoffs are explicit: each stage's inputs table lists the previous-stage outputs it needs, and the agent loads only those.

Two patterns worth pulling out from this workspace specifically.

The gated stage. Stage 04, Extended Notes, only runs if I explicitly ask for them. The gate isn't inside stage 04 itself. The stage exists; its CONTEXT.md is a normal stage contract. The gate lives in the workspace's top-level CLAUDE.md instructions, in the routing table that decides which stages run for which kind of request. "If the user asked for extended notes, run stage 04. Otherwise skip to stage 05." This pattern lets a workspace handle optional depth without complicating the linear flow. The default run does four stages; the on-request run does five. The gating logic sits in one place (the routing table), not duplicated across the stages it gates.

The delivery checkpoint. Stage 05, Assemble & Deliver, pauses before writing the final file. Its CONTEXT.md has a Checkpoints section that says: "Confirm the destination folder with the user before writing. Show the proposed path. Wait for explicit go-ahead." The agent presents the path, I confirm or redirect, then it writes. This is the only human-in-the-loop moment in the workspace, and it's the one that matters: a folder write is irreversible enough to warrant a confirm. Everything before it can be re-run if the output is bad. The folder write commits the result.

The bigger one: content-to-guide

content-to-guide is the same shape, larger. It takes long-form material (videos, PDFs, transcripts, books) and produces chapter-organized reader's guides. Seven stages, source-type configuration, two checkpoints, bundled skills:

content-to-guide/
├── CLAUDE.md
├── CONTEXT.md
├── shared/                     # voice profiles, takeaway arc, format rules
├── source-types/               # per-source-type config (one file per type)
├── references/                 # pandoc / Calibre recipes, format gotchas
├── skills/                     # YouTube fetch, PDF/EPUB build (plug-ins)
└── stages/
    ├── 01-detect-and-setup/
    ├── 02-extract-text/
    ├── 03-identify-chapters/   # CHECKPOINT
    ├── 04-split-text/
    ├── 05-summarize-chapters/  # parallel agents per chapter
    ├── 06-build-pdf/           # CHECKPOINT
    └── 07-build-kindle/        # optional EPUB + MOBI delivery

The core flow is straightforward: identify what kind of source the user dropped, extract text from it, identify chapter boundaries, split the text by chapters, summarize each chapter, build the PDF. Stage 07 is optional Kindle delivery for users who want EPUB or MOBI.

Three patterns this workspace adds beyond what meeting-summarizer shows.

Source-type config. Different inputs (YouTube single video, YouTube multi-video bundle, PDF research paper, PDF book, transcript, long webpage) load different per-source config files at stage 01. The pipeline shape stays the same; only the configuration varies. The source-types/ folder has one markdown file per source type, each declaring the default voice, the output base path, the takeaway-arc requirements, and the source-specific gotchas. Stage 01's process: detect the source type from the input shape, ask the user if ambiguous, load the matching config, and proceed. The configuration is data, not code. Adding a new source type means adding a new markdown file, not modifying any stage.

Bundled skills. The workspace ships with its own skills/ folder for capabilities the stages will need: fetch a YouTube transcript, render a PDF, build an EPUB. Skills get loaded only at the stage that needs them, so the per-stage context stays lean. Stage 02 loads the YouTube-fetch skill if the source is YouTube; stage 06 loads the PDF-build skill; stage 07 loads the EPUB-build skill. The workspace is self-contained. You can copy it to a new machine, point an agent at it, and it has everything it needs without external dependencies on a global skills folder.

A two-checkpoint flow. Stage 03 (chapter boundaries) and stage 06 (PDF preview) both pause for human review. Most workspaces don't need two; this one does because both choices are creative: which chapters and what does this read like as a finished document. Chapter boundaries are subjective. A 90-minute talk could be 5 chapters or 12, and the right answer depends on how the reader will use the guide. Stage 03 proposes boundaries, the human approves or redirects, then stage 04 splits the text accordingly. Stage 06 builds a PDF preview; the human reads it, flags any layout or content issues, and approves the final build. Two creative checkpoints in one workflow is unusual. It's worth it here because both decisions affect the output materially and neither is automatable.

The convention layer that keeps this portable

The reason this whole approach is worth investing in: the convention is open. Every ICM workspace has a CLAUDE.md at the root because that's what the Claude family of tools (Claude Code, Cowork, Claude Desktop) reads automatically when a folder opens. But you can also drop an AGENTS.md next to it (same content, different filename) and the workspace runs on Cursor, Codex CLI, GitHub Copilot, Windsurf, Amp, and Devin too. AGENTS.md is the open standard, backed by the Linux Foundation Agentic AI Foundation, adopted by 60,000+ repositories, endorsed by every major agent platform that doesn't have its own competing convention. Same workspace, multiple harnesses.

Practically, an ICM workspace that wants maximum portability includes both files: the CLAUDE.md for the Anthropic ecosystem and the AGENTS.md for everyone else. The content can be near-identical (most of the routing is tool-agnostic), with small tool-specific differences pushed into separate files the main map references. The discipline is the same as the rest of ICM: keep canonical sources in one place, point at them from wherever they're needed.

The point isn't that you'll personally run your workspace through six different tools today. The point is that when the next harness ships, and one will, your folder is ready. The convention layer is what makes ICM workspaces survive tool churn. The structure of your work stays independent of any specific tool that runs it. Tools come and go; the folder persists.

Running it in Cowork

Cowork is the natural runner for ICM workspaces if you're not a developer. Mac/Windows desktop app, file-system-native, designed for non-coding knowledge workers, reads CLAUDE.md automatically when you point it at a folder. The end-to-end run looks like this:

Open Cowork. Drag the meeting-summarizer folder into the workspace pane (or browse to it). Cowork reads the workspace's CLAUDE.md and presents the workspace summary: "This is a meeting summarization workspace. Drop a transcript path or file to get started." Drop a transcript file into the chat, or paste a path. Cowork runs stage 01: reads the transcript, writes comprehensive notes to stages/01-meeting-notes/output/notes.md. Then stage 02: reads transcript and notes, extracts action items. Then stage 03: reads transcript and notes, identifies key insights. No pauses through these; the agent moves automatically through the unreviewed stages. Stage 04 is skipped because no extended notes were requested. Stage 05 hits, and Cowork pauses: "This will write the final summary to ~/Obsidian/Meetings/2026-05-04-onai-product-review.md, proceed?" I confirm. The file is written. Done. None of it needed code, a terminal, or any framework knowledge. The agent did the work the workspace declared it would do, in the order the workspace declared it would do it, with the one human checkpoint the workspace declared it would have.

If the workspace doesn't exist yet, there's a downloadable skill that walks new users through building one. icm-workspace-builder, available from the landing page, is interview-driven: drop it into Cowork's skills folder, then say "build an ICM workspace for topic." It'll ask eight questions about the workflow (the job in one sentence, the inputs, the outputs, the steps, the human checkpoints, the side effects) and scaffold the folder. Same shape as the workspaces above, generated to match the user's specific work.

ICM gets you a clean workflow specification. What it doesn't get you, today, is production-grade reliability: durable execution, retries, observability, the ability to recover cleanly when a stage fails after sending an email. Part 5 is honest about that gap and the direction worth moving toward. It's the most aspirational part of the series.

Three takeaways

  1. Stages are optional. A workspace can have stages or it can have a routing table that loads context based on where the conversation is. Match the structure to the work, not the other way around. The newsletter-writer reference workspace has no stages at all; it uses a routing table and human-driven sequencing instead.
  2. Specs define WHAT, never HOW. Stage CONTEXT.md files describe the contract (inputs, outputs, audit checks), not the implementation. The agent has creative latitude inside the contract. Over-constrained specs (component names, exact prompts, pixel positions) are an anti-pattern; they fight the model rather than guide it.
  3. Watch for the known anti-patterns. The ICM source material catalogs the common ones: the context dump (loading everything at once), over-constrained specs (component names and pixel positions), and learning from previous outputs instead of authoritative reference docs. Avoiding those goes a long way.

Cross-references

Sources

All ICM parts