rindig/interpreted-context-methdology

1. What this repo is

This is not a software application in the usual sense; it is a repository of filesystem-based AI workflows. The core idea is that folder structure, markdown prompts, and staged output files replace a traditional orchestration framework.

2. Repository-level layers

The root contains the methodology and the reusable scaffolding:

- README.md explains the ICM approach.

- CLAUDE.md is the always-loaded top-level agent entrypoint.

- _core/ holds the canonical conventions, placeholder syntax, and reusable templates.

- workspaces/ contains concrete workflows for different domains.

3. The architectural unit: a workspace

Each workspace is a self-contained pipeline with its own:

- CLAUDE.md and CONTEXT.md for routing and role definition

- setup/ questionnaire for one-time configuration

- shared/ domain-wide constants or resources

- skills/ specialized knowledge bundles and helper scripts

- stages/ numbered stage folders with CONTEXT.md, references/, and output/

4. How data moves

The main data flow is stage output becomes the next stage’s input. Each stage writes plain-text artifacts into its output/ directory, and later stages read those files. Humans can edit the output between stages, so the filesystem is both the transport layer and the review surface.

5. How agents are scoped

The repo uses a layered context model:

- root-level Claude instructions

- workspace-level routing context

- stage-level contracts in each CONTEXT.md

- stage references and shared knowledge

- working artifacts from previous stages

This keeps each stage narrowly focused and prevents loading the whole repo into context.

6. Conventions as the real framework

_core/CONVENTIONS.md is the central policy document. It defines the rules that make the system work: one stage per job, one-way references, canonical sources, selective file loading, checkpoints, audits, and questionnaire-driven setup. This file functions like the architecture spec for all workspaces.

7. Workspace-builder subsystem

workspaces/workspace-builder is itself an ICM pipeline for generating new ICM workspaces. Its stages are:

- discovery

- mapping

- scaffolding

- questionnaire design

- validation

This is the meta-workflow that standardizes how new workspaces are created and ensures they follow the conventions.

8. Course-deck-production pipeline

workspaces/course-deck-production turns unstructured source material into polished slide decks. Its stages are:

- extraction

- curriculum

- outline

- generation

- QA delivery

Supporting assets include a design-system/, shared course metadata, and a PPTX skill bundle with OOXML tooling. This workspace is heavily oriented around PowerPoint/PPTX structure, slide patterns, and output validation.

9. Script-to-animation pipeline

workspaces/script-to-animation converts a content idea into a script, then into an animation specification, then into Remotion build output. Its stages are:

- script

- spec

- build

It includes frontend design guidance plus Remotion best-practices docs, which indicate that the final deliverable is code-driven motion graphics rather than a static document.

10. Voice-driven-animation pipeline

workspaces/voice-driven-animation is a more media-rich pipeline:

- research

- script

- voice

- animate

- render

It adds external-media steps through dedicated skills for ElevenLabs narration generation and Whisper-based beat detection/transcription. This workspace bridges text, audio, timing analysis, and Remotion scene construction.

11. Skills as portable capability packs

The skills/ folders are reusable knowledge and helper-script bundles. They are not stages themselves; they are selectively loaded support material. Examples include:

- PPTX/OOXML handling and validation scripts

- Remotion scene and composition best practices

- ElevenLabs audio generation

- Whisper transcription and beat finding

These skills materially shape how stage outputs are produced.

12. Shared, stable configuration versus run-specific artifacts

The repo separates durable configuration from run output:

- shared/ and design-system/ hold stable reference material

- references/ under each stage encode stage-specific rules

- output/ contains transient artifacts for the current run

Output folders are intentionally empty in the repo except for .gitkeep, reinforcing that the important runtime state is generated per execution.

13. Human-in-the-loop control points

This architecture is built for sequential workflows with review gates. Stages can include checkpoints and audits, so the agent pauses, the human can steer, and then the pipeline continues. That makes the system closer to a controlled production line than an autonomous agent swarm.

14. Boundary of the whole system

The repo’s boundary is the workspace folder itself. There is no central server, queue, or database. The important integration points are:

- markdown files as prompts and contracts

- local folders as state

- external tools only where a workspace requires them, such as Remotion, PowerPoint/OOXML tooling, ElevenLabs, or Whisper

The architecture is therefore local-first, file-first, and intentionally transparent.