ICM Project Scaffolder

What this is

The Interpretable Context Methodology (ICM) replaces multi-agent framework orchestration with a plain folder structure. The insight: the filesystem is the architecture. There's no framework code to write — instead,

• stage sequencing is the folder numbering (01_, 02_, 03_ …),
• context scoping is the folder hierarchy (each stage loads only what it needs), and
• state management is the files on disk (one stage's output/ is the next stage's input, and a human can read and edit it in between).

It runs like a Unix pipeline of markdown: each stage does one job, is human-reviewable, and hands a clean artifact to the next. This skill generates that structure so the user can start filling it in immediately.

For the full methodology (the five context layers, the reasoning behind the conventions), read references/methodology.md — do this if the user asks why the structure is shaped this way or wants to go deeper than scaffolding.

The structure it produces

<project>/
├── CLAUDE.md                    # Layer 0 — workspace identity
├── CONTEXT.md                   # Layer 1 — routing across stages
├── stages/
│   ├── 01_<stage>/
│   │   ├── CONTEXT.md           # Layer 2 — this stage's contract (Inputs/Process/Outputs)
│   │   ├── references/          # Layer 3 — stable reference material
│   │   └── output/              # Layer 4 — working artifacts (handoff point)
│   ├── 02_<stage>/ …
│   └── 03_<stage>/ …
└── _config/
    ├── shared/                  # references used by more than one stage
    └── setup/
        └── questionnaire.md     # fill in once, before the first run

How to run it

The whole job is: figure out the project name and the stages, then run the scaffold script. The script is deterministic and idempotent (it skips files that already exist unless --force is passed), so it's safe to re-run.

1. Gather two things

• Project name → becomes the root folder (spaces are fine; it gets slugified to snake_case).
• Stages → an ordered, comma-separated list of the pipeline steps. They're auto-numbered in the order given (01_, 02_, …).

If the user already stated these, use them. If they said "just make me one" or didn't specify stages, don't stall — use the paper's example pipeline (research, script, production) and tell them you did, so they can adjust. Only ask a clarifying question if the project's purpose is genuinely unclear and it would change the stages (e.g. a landing-page build vs. a podcast pipeline have very different stages).

Good stages describe one job each and flow in sequence. A few starting points by project type — adapt, don't treat as fixed:

• Content/media pipeline → research, script, production
• Web build → discovery, wireframe, copy, build, qa
• Research report → gather, analyze, draft, review
• Data pipeline → ingest, clean, model, report

2. Run the script

python3 <skill-dir>/scripts/scaffold.py \
  --name "Project Name" \
  --stages "research, script, production" \
  --dir "."

• --dir is where the workspace folder gets created; default is the current directory. If the user named a target path, pass it.
• --stages is optional; omit it for the default research, script, production.
• Add --force only if the user explicitly wants to overwrite an existing workspace.

The script prints the tree it wrote and which files were new vs. skipped.

3. Report back

Show the user the tree the script produced and tell them the two immediate next steps:

1. Fill in _config/setup/questionnaire.md (the project brief every stage draws on).
2. Open the first stage's CONTEXT.md and replace the _Process_ placeholder with the real instructions for that stage.

Don't pre-fill the stage instructions yourself unless the user asks — the point of ICM is that a human authors and reviews each stage's contract. Offer to help write the first stage's CONTEXT.md if they'd like.

Notes

• Every seeded file is a template with a placeholder, not empty. Each one states its layer and what belongs in it, so the user (or a future agent) can pick it up cold.
• Re-running is safe. To add a stage later, re-run with the new stage list; existing files are skipped. Renumber rather than using 01b-style suffixes so ordering stays obvious.
• _config/ is not a stage — the underscore prefix marks it as system/config so it sorts and reads separately from the numbered pipeline.