# sorretai/icm architecture

> Architecture diagram of the GitHub repository sorretai/icm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sorretai/icm
- Repository: https://github.com/sorretai/icm

## Overview

ICM is a filesystem-based workflow architecture: one agent reads workspace and stage instructions, loads scoped references and prior artifacts, then writes editable outputs for later stages and human review. Numbered stages encode order; markdown files are the handoff and state mechanism. The repository demonstrates this pattern through course-deck, script-animation, voice-animation, and workspace-builder workspaces, with domain skills and configuration alongside them. The README documents the general sequencing and context model; edges for example workspaces reflect their documented stage order, not inspected runtime orchestration.

Main entry points: [`workspaces/voice-driven-animation/stages/02-script/CONTEXT.md`](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/02-script/CONTEXT.md) (Script), [`workspaces/voice-driven-animation/stages/03-voice/CONTEXT.md`](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/03-voice/CONTEXT.md) (Voice Production), [`workspaces/voice-driven-animation/stages/04-animate/CONTEXT.md`](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/04-animate/CONTEXT.md) (Animation), [`workspaces/voice-driven-animation/skills/elevenlabs-narration/scripts/generate-audio.py`](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/skills/elevenlabs-narration/scripts/generate-audio.py) (Narration Tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["ICM Core"]
  node_core_rules["Folder Conventions<br/>[CONVENTIONS.md]"]
  node_templates["Workspace Templates"]
  node_workspace_entry["Workspace Context<br/>[CONTEXT.md]"]
end

subgraph group_deck["Course Deck"]
  node_deck_setup["Setup Questionnaire<br/>[questionnaire.md]"]
  node_deck_config["Brand and Design<br/>[CONTEXT.md]"]
  node_deck_extract["Source Extraction<br/>[CONTEXT.md]"]
  node_deck_curriculum["Curriculum<br/>[CONTEXT.md]"]
  node_deck_outline["Slide Outline<br/>[CONTEXT.md]"]
  node_deck_generate["Deck Generation<br/>[CONTEXT.md]"]
  node_deck_qa["QA and Delivery<br/>[CONTEXT.md]"]
  node_deck_skills["PPTX Skills<br/>[SKILL.md]"]
end

subgraph group_script["Script Animation"]
  node_script_context["Script Context<br/>[CONTEXT.md]"]
  node_script_write["Script Writing<br/>[CONTEXT.md]"]
  node_script_spec["Animation Spec<br/>[CONTEXT.md]"]
  node_script_build["Animation Build<br/>[CONTEXT.md]"]
  node_script_skills["Remotion Guidance<br/>[SKILL.md]"]
end

subgraph group_voice["Voice Animation"]
  node_voice_context["Voice Workflow<br/>[CONTEXT.md]"]
  node_voice_research["Research<br/>[CONTEXT.md]"]
  node_voice_script["Script<br/>[CONTEXT.md]"]
  node_voice_audio["Voice Production<br/>[CONTEXT.md]"]
  node_voice_animate["Animation<br/>[CONTEXT.md]"]
  node_voice_render["Render<br/>[CONTEXT.md]"]
  node_narration["Narration Tool<br/>[generate-audio.py]"]
  node_transcribe["Whisper Transcription<br/>[transcribe.py]"]
  node_beat_finder["Beat Timing<br/>[find-beats.py]"]
end

subgraph group_builder["Workspace Builder"]
  node_workspace_context["Builder Context<br/>[CONTEXT.md]"]
  node_discover["Workflow Discovery<br/>[CONTEXT.md]"]
  node_mapping["Workflow Mapping<br/>[CONTEXT.md]"]
  node_scaffold["Workspace Scaffolding<br/>[CONTEXT.md]"]
  node_questionnaire_design["Questionnaire Design<br/>[CONTEXT.md]"]
  node_validation["Workspace Validation<br/>[CONTEXT.md]"]
end

node_user(("Practitioner"))
node_agent(("Single Agent"))
node_elevenlabs{{"ElevenLabs"}}

node_user -->|"provides task"| node_agent
node_agent -->|"reads conventions"| node_core_rules
node_agent -->|"reads routing"| node_workspace_entry
node_templates -.->|"informs structure"| node_workspace_entry
node_user -->|"sets preferences"| node_deck_setup
node_agent -->|"loads references"| node_deck_config
node_agent -->|"executes stage"| node_deck_extract
node_deck_extract -->|"hands off output"| node_deck_curriculum
node_deck_curriculum -->|"hands off output"| node_deck_outline
node_deck_outline -->|"hands off output"| node_deck_generate
node_deck_generate -->|"hands off deck"| node_deck_qa
node_agent -.->|"loads guidance"| node_deck_skills
node_agent -->|"reads routing"| node_script_context
node_script_context -->|"routes task"| node_script_write
node_script_write -->|"hands off output"| node_script_spec
node_script_spec -->|"hands off specification"| node_script_build
node_agent -.->|"loads guidance"| node_script_skills
node_agent -->|"reads routing"| node_voice_context
node_voice_context -->|"routes task"| node_voice_research
node_voice_research -->|"hands off output"| node_voice_script
node_voice_script -->|"hands off script"| node_voice_audio
node_voice_audio -->|"hands off audio"| node_voice_animate
node_voice_animate -->|"hands off composition"| node_voice_render
node_narration -->|"reads script"| node_voice_script
node_narration -.->|"requests speech"| node_elevenlabs
node_transcribe -->|"reads audio"| node_voice_audio
node_transcribe -->|"writes transcript"| node_beat_finder
node_beat_finder -->|"emits beat timings"| node_voice_animate
node_agent -->|"reads routing"| node_workspace_context
node_workspace_context -->|"routes task"| node_discover
node_discover -->|"hands off findings"| node_mapping
node_mapping -->|"hands off map"| node_scaffold
node_scaffold -->|"hands off workspace"| node_questionnaire_design
node_questionnaire_design -->|"hands off questionnaire"| node_validation

click node_core_rules "https://github.com/sorretai/icm/blob/main/_core/CONVENTIONS.md"
click node_templates "https://github.com/sorretai/icm/tree/main/_core/templates"
click node_workspace_entry "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/CONTEXT.md"
click node_deck_setup "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/setup/questionnaire.md"
click node_deck_config "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/design-system/CONTEXT.md"
click node_deck_extract "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/01-extraction/CONTEXT.md"
click node_deck_curriculum "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/02-curriculum/CONTEXT.md"
click node_deck_outline "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/03-outline/CONTEXT.md"
click node_deck_generate "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/04-generation/CONTEXT.md"
click node_deck_qa "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/05-qa-delivery/CONTEXT.md"
click node_deck_skills "https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/skills/pptx/SKILL.md"
click node_script_context "https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/CONTEXT.md"
click node_script_write "https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/stages/01-script/CONTEXT.md"
click node_script_spec "https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/stages/02-spec/CONTEXT.md"
click node_script_build "https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/stages/03-build/CONTEXT.md"
click node_script_skills "https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/skills/remotion-best-practices/SKILL.md"
click node_voice_context "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/CONTEXT.md"
click node_voice_research "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/01-research/CONTEXT.md"
click node_voice_script "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/02-script/CONTEXT.md"
click node_voice_audio "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/03-voice/CONTEXT.md"
click node_voice_animate "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/04-animate/CONTEXT.md"
click node_voice_render "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/05-render/CONTEXT.md"
click node_narration "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/skills/elevenlabs-narration/scripts/generate-audio.py"
click node_transcribe "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/skills/whisper-beat-finder/scripts/transcribe.py"
click node_beat_finder "https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/skills/whisper-beat-finder/scripts/find-beats.py"
click node_workspace_context "https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/CONTEXT.md"
click node_discover "https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/01-discovery/CONTEXT.md"
click node_mapping "https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/02-mapping/CONTEXT.md"
click node_scaffold "https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/03-scaffolding/CONTEXT.md"
click node_questionnaire_design "https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/04-questionnaire-design/CONTEXT.md"
click node_validation "https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/05-validation/CONTEXT.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_rules,node_templates,node_workspace_entry toneBlue
class node_deck_setup,node_deck_config,node_deck_extract,node_deck_curriculum,node_deck_outline,node_deck_generate,node_deck_qa,node_deck_skills toneAmber
class node_script_context,node_script_write,node_script_spec,node_script_build,node_script_skills toneMint
class node_voice_context,node_voice_research,node_voice_script,node_voice_audio,node_voice_animate,node_voice_render,node_narration,node_transcribe,node_beat_finder toneRose
class node_workspace_context,node_discover,node_mapping,node_scaffold,node_questionnaire_design,node_validation,node_user,node_agent,node_elevenlabs toneIndigo
```

## Components

### ICM Core

- [Folder Conventions](https://github.com/sorretai/icm/blob/main/_core/CONVENTIONS.md): `_core/CONVENTIONS.md`
- [Workspace Templates](https://github.com/sorretai/icm/tree/main/_core/templates): `_core/templates`
- [Workspace Context](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/CONTEXT.md): `workspaces/course-deck-production/CONTEXT.md`

### Course Deck

- [Setup Questionnaire](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/setup/questionnaire.md): `workspaces/course-deck-production/setup/questionnaire.md`
- [Brand and Design](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/design-system/CONTEXT.md): `workspaces/course-deck-production/design-system/CONTEXT.md`
- [Source Extraction](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/01-extraction/CONTEXT.md): `workspaces/course-deck-production/stages/01-extraction/CONTEXT.md`
- [Curriculum](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/02-curriculum/CONTEXT.md): `workspaces/course-deck-production/stages/02-curriculum/CONTEXT.md`
- [Slide Outline](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/03-outline/CONTEXT.md): `workspaces/course-deck-production/stages/03-outline/CONTEXT.md`
- [Deck Generation](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/04-generation/CONTEXT.md): `workspaces/course-deck-production/stages/04-generation/CONTEXT.md`
- [QA and Delivery](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/stages/05-qa-delivery/CONTEXT.md): `workspaces/course-deck-production/stages/05-qa-delivery/CONTEXT.md`
- [PPTX Skills](https://github.com/sorretai/icm/blob/main/workspaces/course-deck-production/skills/pptx/SKILL.md): `workspaces/course-deck-production/skills/pptx/SKILL.md`

### Script Animation

- [Script Context](https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/CONTEXT.md): `workspaces/script-to-animation/CONTEXT.md`
- [Script Writing](https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/stages/01-script/CONTEXT.md): `workspaces/script-to-animation/stages/01-script/CONTEXT.md`
- [Animation Spec](https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/stages/02-spec/CONTEXT.md): `workspaces/script-to-animation/stages/02-spec/CONTEXT.md`
- [Animation Build](https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/stages/03-build/CONTEXT.md): `workspaces/script-to-animation/stages/03-build/CONTEXT.md`
- [Remotion Guidance](https://github.com/sorretai/icm/blob/main/workspaces/script-to-animation/skills/remotion-best-practices/SKILL.md): `workspaces/script-to-animation/skills/remotion-best-practices/SKILL.md`

### Voice Animation

- [Voice Workflow](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/CONTEXT.md): `workspaces/voice-driven-animation/CONTEXT.md`
- [Research](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/01-research/CONTEXT.md): `workspaces/voice-driven-animation/stages/01-research/CONTEXT.md`
- [Script](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/02-script/CONTEXT.md): `workspaces/voice-driven-animation/stages/02-script/CONTEXT.md`
- [Voice Production](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/03-voice/CONTEXT.md): `workspaces/voice-driven-animation/stages/03-voice/CONTEXT.md`
- [Animation](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/04-animate/CONTEXT.md): `workspaces/voice-driven-animation/stages/04-animate/CONTEXT.md`
- [Render](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/stages/05-render/CONTEXT.md): `workspaces/voice-driven-animation/stages/05-render/CONTEXT.md`
- [Narration Tool](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/skills/elevenlabs-narration/scripts/generate-audio.py): `workspaces/voice-driven-animation/skills/elevenlabs-narration/scripts/generate-audio.py`
- [Whisper Transcription](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/skills/whisper-beat-finder/scripts/transcribe.py): `workspaces/voice-driven-animation/skills/whisper-beat-finder/scripts/transcribe.py`
- [Beat Timing](https://github.com/sorretai/icm/blob/main/workspaces/voice-driven-animation/skills/whisper-beat-finder/scripts/find-beats.py): `workspaces/voice-driven-animation/skills/whisper-beat-finder/scripts/find-beats.py`

### Workspace Builder

- [Builder Context](https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/CONTEXT.md): `workspaces/workspace-builder/CONTEXT.md`
- [Workflow Discovery](https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/01-discovery/CONTEXT.md): `workspaces/workspace-builder/stages/01-discovery/CONTEXT.md`
- [Workflow Mapping](https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/02-mapping/CONTEXT.md): `workspaces/workspace-builder/stages/02-mapping/CONTEXT.md`
- [Workspace Scaffolding](https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/03-scaffolding/CONTEXT.md): `workspaces/workspace-builder/stages/03-scaffolding/CONTEXT.md`
- [Questionnaire Design](https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/04-questionnaire-design/CONTEXT.md): `workspaces/workspace-builder/stages/04-questionnaire-design/CONTEXT.md`
- [Workspace Validation](https://github.com/sorretai/icm/blob/main/workspaces/workspace-builder/stages/05-validation/CONTEXT.md): `workspaces/workspace-builder/stages/05-validation/CONTEXT.md`

### Other components

- **Practitioner**
- **Single Agent**
- **ElevenLabs**

## Connections

- Practitioner → Single Agent: provides task
- Single Agent → Folder Conventions: reads conventions
- Single Agent → Workspace Context: reads routing
- Workspace Templates → Workspace Context: informs structure
- Practitioner → Setup Questionnaire: sets preferences
- Single Agent → Brand and Design: loads references
- Single Agent → Source Extraction: executes stage
- Source Extraction → Curriculum: hands off output
- Curriculum → Slide Outline: hands off output
- Slide Outline → Deck Generation: hands off output
- Deck Generation → QA and Delivery: hands off deck
- Single Agent → PPTX Skills: loads guidance
- Single Agent → Script Context: reads routing
- Script Context → Script Writing: routes task
- Script Writing → Animation Spec: hands off output
- Animation Spec → Animation Build: hands off specification
- Single Agent → Remotion Guidance: loads guidance
- Single Agent → Voice Workflow: reads routing
- Voice Workflow → Research: routes task
- Research → Script: hands off output
- Script → Voice Production: hands off script
- Voice Production → Animation: hands off audio
- Animation → Render: hands off composition
- Narration Tool → Script: reads script
- Narration Tool → ElevenLabs: requests speech
- Whisper Transcription → Voice Production: reads audio
- Whisper Transcription → Beat Timing: writes transcript
- Beat Timing → Animation: emits beat timings
- Single Agent → Builder Context: reads routing
- Builder Context → Workflow Discovery: routes task
- Workflow Discovery → Workflow Mapping: hands off findings
- Workflow Mapping → Workspace Scaffolding: hands off map
- Workspace Scaffolding → Questionnaire Design: hands off workspace
- Questionnaire Design → Workspace Validation: hands off questionnaire