This is the shortest path from “I installed the package” to “I understand the loop.”
The goal is not to finish a full workflow. The goal is to see the ICM rhythm once:
Use a virtual environment so the trial stays clean:
python -m venv .venv
source .venv/bin/activate
python -m pip install icm-workspace-template
icm --version
Expected version for this release:
icm 0.19.0
icm new my-first-icm-workspace --name "My First ICM Workspace" --with-common-artifacts
cd my-first-icm-workspace
The --with-common-artifacts flag adds starter files for source inventories, release calendars, and decision logs. You can ignore them at first, but they are useful once a workflow needs traceability.
Open this file:
stages/00_intake/output/project-brief.md
Paste a small brief:
# Project Brief
## Project Name
Weekly Research Digest
## Desired Outcome
A repeatable workflow for turning source links and notes into a concise weekly research digest.
## Starting Material
- Source links collected during the week
- Notes from the project owner
## Audience Or Users
Busy technical readers who want the important points without reading every source.
## Success Criteria
- Claims cite their source material.
- A human reviews the outline before final drafting.
- The workflow can be repeated next week.
## Constraints
- Keep the first version small.
- Use markdown files and normal coding-agent tools.
- Avoid unsourced claims.
## Natural Review Points
- After source triage
- After outline
- Before final publication
## Open Questions
- How long should the digest be?
- Should the workflow create social posts too?
Use this prompt:
Read AGENTS.md and CONTEXT.md, then run stages/00_intake.
Load only the inputs declared in stages/00_intake/CONTEXT.md.
Write only the declared outputs, run Verify, and stop at the Review Gate.
The important part is “one stage.” ICM works because each handoff is small enough to inspect.
Read:
stages/00_intake/output/project-brief.md
Edit it directly if needed. The file is now the source of truth for the next stage.
Record the human acceptance in plain markdown:
icm accept stages/00_intake --reviewer "Hobo" --note "Brief is ready for discovery."
Then ask:
Run stages/01_discovery using the approved output from stages/00_intake.
Write the declared output, run Verify, and stop at the Review Gate.
Run:
icm doctor .
icm validate . --strict
icm doctor explains what needs attention. icm validate --strict confirms the workspace structure is still sound.
You have seen the whole loop:
| Habit | Why It Matters |
|---|---|
| One numbered stage at a time | Keeps context small and reviewable |
| Markdown contracts | Makes instructions visible |
| Output files as handoffs | Gives the next stage a stable input |
| Review gates | Lets humans stop drift early |
| Doctor and validate | Separates repair guidance from structure checks |
icm status . to see stage state.icm next . to see the likely next stage.icm explain stages/01_discovery to inspect the stage contract.icm review stages/01_discovery after the discovery output exists.icm accept stages/01_discovery when a human approves the discovery handoff.icm dashboard . when you want a read-only browser view.