How codeprotege/soul works
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