# codeprotege/soul architecture

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

- Interactive diagram: https://gitdiagram.com/codeprotege/soul
- Repository: https://github.com/codeprotege/soul

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **not a traditional software application** (no `src/`, `package.json`, `Dockerfile`, etc.). It’s a **structured “agent system” / knowledge-and-workflow specification** for SOUL: a set of markdown “modules” that define:

- **Controller rules & read order** (`AGENTS.md`)
- **Mission/scope/constraints** (`Overarch.md`)
- **Metadata taxonomy + file relationships** (`Collab.md`)
- **Shared memory / session log** (`Exp.md`)
- **Specialized role profiles (“subagents”)** (`subagent/`, plus many top-level `*.md` role files)

##### Top-level “core governance + memory”
- `AGENTS.md` — the “controller” rules and read order (central orchestrator spec)
- `Overarch.md` — mission/scope/constraints (system boundary + non-functional rules)
- `Collab.md` — metadata tags + relationships between files (ontology/graph)
- `Exp.md` — shared session memory (append-only log, newest first)

##### Role profiles / agents (capability modules)
There are many specialized markdowns:
- `actuarial-task-analyzer.md`
- `armstrong-ecm-analyst.md`
- `data-pipeline-surgeon.md`
- `data-visualizer.md`
- `deduction-master.md`
- `ecm-std-coordinator.md`
- `hypothesis-scientist.md`
- `info-io-operator.md`
- `mece-framework-analyst.md`
- `palantir-field-engineer.md`
- `project-initiator.md`
- `russian-doll-analyzer.md`
- `web-scraping-specialist.md`

These function like **plug-in profiles**: each defines behavior, expertise, and likely input/output conventions.

##### Subagent directories
- `subagent/` (mentioned in README as the canonical location for specialized profiles)
- `subagents/` (also present; potential duplication or alternate namespace)
- `subagents/test.md` (indicates testing or example profile)

##### What the README adds (runtime model & conventions)
- **Explicit metadata** (frontmatter-like metadata in README itself suggests a pattern)
- **Workflow registry + update log** (`workflow.md`)
- **Reusable snippet library** (`codebase.md`)
- **Shared memory across sessions** (`Exp.md`)
- **A defined read order / controller rules** (`AGENTS.md`)
- **Tagging + relationships as a first-class system** (`Collab.md`)

This is essentially an **agent operating system** made of documents.

##### Orchestration / Control Plane
- `AGENTS.md` (Controller rules & read order)
- (Optionally) “Controller Agent Runtime” as an abstract node (because the repo is spec-only)

##### Governance / Constraints
- `Overarch.md` (mission, scope, constraints)

##### Knowledge Plane (Metadata + Memory)
- `Collab.md` (tags, relationships, ontology)
- `Exp.md` (shared memory log)

##### Capability Plane (Role Profiles / Subagents)
- `subagent/` and/or `subagents/` as containers

Model **how work happens**:

##### Task Intake → Controller
- “User Task / Prompt” → (abstract) “Controller Runtime”
- Controller Runtime → reads `AGENTS.md` (rule/read order)

##### Controller consults governance + metadata
- Controller Runtime → `Overarch.md` (constraints & mission)
- Controller Runtime ↔ `Collab.md` (tags used to select roles, link files)

##### Role selection & execution
- Controller Runtime → selects one/more role profiles (e.g., `data-visualizer.md`)
- Role profile → produces “Work Output / Artifacts / Recommendations”
- Role profile ↔ `codebase.md` (reuse snippets) (if present)
- Role profile ↔ `workflow.md` (register new workflows) (if present)

##### Memory update loop
- Controller Runtime / Role profile → append/update `Exp.md` (shared session memory)
- Controller Runtime → consult `Exp.md` at start of new session (shared continuity)

- “New tags discovered” → update `Collab.md`
- “New workflow created” → update `workflow.md`
- “Reusable snippet created” → update `codebase.md`

##### Architectural patterns / principles
- **Document-as-Source-of-Truth**: markdown files are authoritative modules
- **Control plane vs capability plane separation**: `AGENTS.md` governs; role files execute
- **Shared memory**: `Exp.md` is a persistent log enabling cross-session continuity
- **Metadata-driven routing**: `Collab.md` tags/relationships drive agent selection and file discovery
- **Extensible plugin architecture**: new `*.md` role profiles can be added without changing “runtime” code

##### Relevant technologies/frameworks
There’s no code framework here; the “tech” is:
- Markdown modules with structured metadata (frontmatter-like schema)
- A conceptual agent runtime (LLM/controller) that interprets the documents

- Actors: User, Controller Runtime (external)
- System boundary: SOUL repo (documents)
- The 4 planes (Control/Governance/Knowledge/Capabilities)
- Step-by-step: intake → consult rules → consult constraints → select agent → produce output → update memory/metadata/workflows

##### “Separate into as many components as possible” (how to do that without chaos)
To be very detailed *and* readable:
- Inside the **Capabilities plane**, either:
- Every role file as its own node (best fidelity), or
- Into clusters by function (Data, Reasoning, Ops, Initiation), while still naming each file inside the cluster.
- Both `subagent/` and `subagents/` as separate containers and annotate: “Potential duplication / reconcile”.

A small **“Repository Index”** sidebar that lists:
- Core files
- Role modules
- Subagent directories
- Referenced-but-not-present files

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 0: System Context
  %% =========================
  User["User / Task Prompt"]:::external
  Runtime["LLM/Agent Runtime (external)"]:::external

  subgraph "SOUL Document System (Repository Boundary)"
    direction TB

    Readme["README.md\nRepository overview & conventions\n(runtime model described)"]:::doc

    %% =========================
    %% Level 1: Planes / Modules
    %% =========================
    subgraph "Orchestration / Control Plane"
      direction TB
      Agents["AGENTS.md\nController rules & read order"]:::control
    end

    subgraph "Governance / Constraints"
      direction TB
      Overarch["Overarch.md\nMission / scope / constraints"]:::control
    end

    subgraph "Knowledge Plane (Metadata + Memory)"
      direction TB
      Collab["Collab.md\nMetadata taxonomy + file relationships"]:::store
      Exp["Exp.md\nShared memory log\n(append-only, newest-first)"]:::store

      Workflow["workflow.md\nWorkflow registry + update log\n(referenced; not in tree)"]:::missing
      Codebase["codebase.md\nReusable snippet library\n(referenced; not in tree)"]:::missing
    end

    subgraph "Capability Plane (Role Profiles / Subagents)"
      direction TB

      subgraph "Role Profiles (Top-level *.md modules)"
        direction TB

        subgraph "Initiation"
          direction TB
          ProjectInitiator["project-initiator.md\nRole profile"]:::role
        end

        subgraph "Reasoning & Analysis"
          direction TB
          Actuarial["actuarial-task-analyzer.md\nRole profile"]:::role
          Deduction["deduction-master.md\nRole profile"]:::role
          Hypothesis["hypothesis-scientist.md\nRole profile"]:::role
          MECE["mece-framework-analyst.md\nRole profile"]:::role
          RussianDoll["russian-doll-analyzer.md\nRole profile"]:::role
        end

        subgraph "Data / Engineering / Ops"
          direction TB
          DataPipeline["data-pipeline-surgeon.md\nRole profile"]:::role
          DataViz["data-visualizer.md\nRole profile"]:::role
          InfoIO["info-io-operator.md\nRole profile"]:::role
          WebScrape["web-scraping-specialist.md\nRole profile"]:::role
        end

        subgraph "Domain Specialists"
          direction TB
          Armstrong["armstrong-ecm-analyst.md\nRole profile"]:::role
          ECMSTD["ecm-std-coordinator.md\nRole profile"]:::role
          Palantir["palantir-field-engineer.md\nRole profile"]:::role
        end
      end

      subgraph "Subagent Containers (specialized profiles)"
        direction TB
        SubagentDir["subagent/\nCanonical specialized profiles directory"]:::container
        SubagentsDir["subagents/\nAlternate/duplicate directory\n(reconcile)"]:::container
        SubagentsTest["subagents/test.md\nTest/example profile"]:::role
      end
    end

    %% =========================
    %% Repository Index (sidebar)
    %% =========================
    subgraph "Repository Index (Artifacts as modules)"
      direction TB
      IndexCore["Core Governance + Memory\n- AGENTS.md\n- Overarch.md\n- Collab.md\n- Exp.md\n- README.md"]:::index
      IndexCap["Capability Modules\n- Multiple role *.md\n- subagent/\n- subagents/"]:::index
      IndexRef["Referenced but Missing\n- workflow.md\n- codebase.md"]:::indexMissing
    end
  end

  %% =========================
  %% Key runtime interactions / flows
  %% =========================
  User -->|"submits_task"| Runtime
  Runtime -->|"consults_conventions"| Readme

  Runtime -->|"reads_rules"| Agents
  Runtime -->|"reads_constraints"| Overarch
  Runtime <-->|"uses_tags_and_relationships"| Collab
  Runtime -->|"consults_memory"| Exp

  Runtime -->|"selects_roles"| ProjectInitiator
  Runtime -->|"selects_roles"| Actuarial
  Runtime -->|"selects_roles"| Deduction
  Runtime -->|"selects_roles"| Hypothesis
  Runtime -->|"selects_roles"| MECE
  Runtime -->|"selects_roles"| RussianDoll
  Runtime -->|"selects_roles"| DataPipeline
  Runtime -->|"selects_roles"| DataViz
  Runtime -->|"selects_roles"| InfoIO
  Runtime -->|"selects_roles"| WebScrape
  Runtime -->|"selects_roles"| Armstrong
  Runtime -->|"selects_roles"| ECMSTD
  Runtime -->|"selects_roles"| Palantir
  Runtime -->|"selects_specialized_profiles"| SubagentDir
  Runtime -->|"selects_specialized_profiles"| SubagentsDir

  %% Outputs + self-updating documentation loop
  subgraph "Outputs & Controlled Knowledge Evolution Loop"
    direction TB
    Output["Work Output / Artifacts / Recommendations"]:::output
    NewTags["New tags discovered"]:::loop
    NewWorkflow["New workflow created"]:::loop
    NewSnippet["Reusable snippet created"]:::loop
  end

  ProjectInitiator -->|"produces"| Output
  Actuarial -->|"produces"| Output
  Deduction -->|"produces"| Output
  Hypothesis -->|"produces"| Output
  MECE -->|"produces"| Output
  RussianDoll -->|"produces"| Output
  DataPipeline -->|"produces"| Output
  DataViz -->|"produces"| Output
  InfoIO -->|"produces"| Output
  WebScrape -->|"produces"| Output
  Armstrong -->|"produces"| Output
  ECMSTD -->|"produces"| Output
  Palantir -->|"produces"| Output
  SubagentsTest -->|"produces"| Output

  Runtime -->|"appends_session_log"| Exp
  Output -->|"summarize_into_memory"| Exp

  Output -->|"identify"| NewTags
  Output -->|"define"| NewWorkflow
  Output -->|"extract"| NewSnippet

  NewTags -->|"update"| Collab
  NewWorkflow -->|"register"| Workflow
  NewSnippet -->|"add"| Codebase

  %% Role profiles may reference/register missing artifacts
  Actuarial <-->|"reuse_snippets"| Codebase
  Deduction <-->|"reuse_snippets"| Codebase
  DataPipeline <-->|"reuse_snippets"| Codebase
  DataViz <-->|"reuse_snippets"| Codebase
  WebScrape <-->|"reuse_snippets"| Codebase
  InfoIO <-->|"reuse_snippets"| Codebase

  ProjectInitiator <-->|"register_workflows"| Workflow
  DataPipeline <-->|"register_workflows"| Workflow
  InfoIO <-->|"register_workflows"| Workflow

  %% Highlight key architectural patterns (as anchored notes)
  subgraph "Architectural Patterns (Annotations)"
    direction TB
    P1["Document-as-Source-of-Truth\nMarkdown modules are authoritative"]:::note
    P2["Control vs Capability Separation\nAGENTS governs; roles execute"]:::note
    P3["Shared Memory\nExp.md enables cross-session continuity"]:::note
    P4["Metadata-driven Routing\nCollab tags drive selection/discovery"]:::note
    P5["Extensible Plugin Architecture\nAdd new role *.md without code changes"]:::note
  end

  Agents -->|"enforces"| P2
  Readme -->|"describes"| P1
  Exp -->|"enables"| P3
  Collab -->|"drives"| P4
  SubagentDir -->|"extends"| P5

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click Agents "https://github.com/codeprotege/soul/blob/main/AGENTS.md"
  click Overarch "https://github.com/codeprotege/soul/blob/main/Overarch.md"
  click Collab "https://github.com/codeprotege/soul/blob/main/Collab.md"
  click Exp "https://github.com/codeprotege/soul/blob/main/Exp.md"
  click Readme "https://github.com/codeprotege/soul/blob/main/README.md"

  click Actuarial "https://github.com/codeprotege/soul/blob/main/actuarial-task-analyzer.md"
  click Armstrong "https://github.com/codeprotege/soul/blob/main/armstrong-ecm-analyst.md"
  click DataPipeline "https://github.com/codeprotege/soul/blob/main/data-pipeline-surgeon.md"
  click DataViz "https://github.com/codeprotege/soul/blob/main/data-visualizer.md"
  click Deduction "https://github.com/codeprotege/soul/blob/main/deduction-master.md"
  click ECMSTD "https://github.com/codeprotege/soul/blob/main/ecm-std-coordinator.md"
  click Hypothesis "https://github.com/codeprotege/soul/blob/main/hypothesis-scientist.md"
  click InfoIO "https://github.com/codeprotege/soul/blob/main/info-io-operator.md"
  click MECE "https://github.com/codeprotege/soul/blob/main/mece-framework-analyst.md"
  click Palantir "https://github.com/codeprotege/soul/blob/main/palantir-field-engineer.md"
  click ProjectInitiator "https://github.com/codeprotege/soul/blob/main/project-initiator.md"
  click RussianDoll "https://github.com/codeprotege/soul/blob/main/russian-doll-analyzer.md"
  click WebScrape "https://github.com/codeprotege/soul/blob/main/web-scraping-specialist.md"

  click SubagentDir "https://github.com/codeprotege/soul/tree/main/subagent/"
  click SubagentsDir "https://github.com/codeprotege/soul/tree/main/subagents/"
  click SubagentsTest "https://github.com/codeprotege/soul/blob/main/subagents/test.md"

  %% =========================
  %% Styles (Color coding)
  %% =========================
  classDef external fill:#111827,stroke:#93C5FD,stroke-width:2px,color:#E5E7EB
  classDef control fill:#1D4ED8,stroke:#0B2A6F,stroke-width:2px,color:#FFFFFF
  classDef store fill:#065F46,stroke:#064E3B,stroke-width:2px,color:#ECFDF5
  classDef role fill:#F59E0B,stroke:#92400E,stroke-width:2px,color:#111827
  classDef container fill:#7C2D12,stroke:#451A03,stroke-width:2px,color:#FFEDD5
  classDef doc fill:#0EA5E9,stroke:#075985,stroke-width:2px,color:#F0F9FF
  classDef missing fill:#10B981,stroke:#047857,stroke-width:2px,color:#ECFDF5,stroke-dasharray: 6 4
  classDef index fill:#334155,stroke:#0F172A,stroke-width:1px,color:#E2E8F0
  classDef indexMissing fill:#334155,stroke:#0F172A,stroke-width:1px,color:#E2E8F0,stroke-dasharray: 6 4
  classDef output fill:#A78BFA,stroke:#5B21B6,stroke-width:2px,color:#111827
  classDef loop fill:#F472B6,stroke:#9D174D,stroke-width:2px,color:#111827
  classDef note fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#111827,stroke-dasharray: 4 3
```
