# idikuterke/onoz-brain architecture

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

- Interactive diagram: https://gitdiagram.com/idikuterke/onoz-brain
- Repository: https://github.com/idikuterke/onoz-brain

## Overview

onoz-brain is a model-independent Python CLI that shares skills across linked projects and records their outcomes for evidence-based promotion. The main loop is project linking → agent briefing → skill execution/verification → run logging → stats and human-approved promotion. It also provides project health/activity dashboards, evals, lessons, and anonymized exports. Most orchestration lives in brain.py; the README documents several capabilities whose implementation details were not sampled, so those links cite the README rather than implying source inspection.

Main entry points: [`brain.py`](https://github.com/idikuterke/onoz-brain/blob/master/brain.py) (Brain CLI), [`skills/anonim-export/scripts/brain_export.py`](https://github.com/idikuterke/onoz-brain/blob/master/skills/anonim-export/scripts/brain_export.py) (Anonymous exporter), [`skills/kos/kos.py`](https://github.com/idikuterke/onoz-brain/blob/master/skills/kos/kos.py) (Skill runner), [`memory/runs`](https://github.com/idikuterke/onoz-brain/tree/master/memory/runs) (Run ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Project workflow"]
  node_brain["Brain CLI<br/>[brain.py]"]
  node_projects[("Project registry<br/>[brain.py]")]
  node_projectrepos["Project repositories"]
  node_briefing["Agent briefing<br/>[brain.py]"]
  node_kos["Skill runner<br/>[kos.py]"]
end

subgraph group_skills["Skills and evidence"]
  node_skilllib["Skill library"]
  node_lessons["Lessons"]
end

subgraph group_oversight["Measurement and oversight"]
  node_runlog[("Run ledger")]
  node_promotion["Promotion rules<br/>[brain.py]"]
  node_stats["Run statistics<br/>[brain.py]"]
  node_evaltasks["Eval task sets"]
  node_evalrunner["Eval runner<br/>[brain.py]"]
  node_evalrecords[("Eval records")]
  node_health["Project health<br/>[brain.py]"]
  node_activity["Commit activity<br/>[brain.py]"]
  node_dashboard["Read-only dashboard<br/>[brain.py]"]
end

subgraph group_exports["Data export"]
  node_exporter["Anonymous exporter<br/>[brain_export.py]"]
  node_exportdata["Export package"]
end

node_user(("Engineer"))
node_agent(("External agent"))

node_user -->|"runs commands"| node_brain
node_brain -->|"links projects"| node_projects
node_projects -->|"marks project root"| node_projectrepos
node_brain -->|"builds context"| node_briefing
node_briefing -->|"briefs"| node_agent
node_agent -->|"works in"| node_projectrepos
node_user -->|"runs skill"| node_kos
node_kos -->|"loads verification"| node_skilllib
node_kos -->|"runs verification"| node_projectrepos
node_kos -->|"invokes log"| node_brain
node_brain -->|"records runs"| node_runlog
node_user -->|"adds lessons"| node_brain
node_brain -->|"stores rules"| node_lessons
node_brain -->|"summarizes runs"| node_stats
node_brain -->|"calculates candidates"| node_promotion
node_runlog -->|"supplies evidence"| node_promotion
node_user -->|"approves apply"| node_promotion
node_user -->|"runs eval"| node_evalrunner
node_evalrunner -->|"selects task"| node_evaltasks
node_evalrunner -->|"tests project"| node_projectrepos
node_evalrunner -->|"records results"| node_evalrecords
node_brain -->|"collects status"| node_health
node_health -->|"reads git state"| node_projectrepos
node_brain -->|"classifies commits"| node_activity
node_activity -->|"reads commit history"| node_projectrepos
node_brain -->|"generates view"| node_dashboard
node_health -->|"feeds health"| node_dashboard
node_activity -->|"feeds activity"| node_dashboard
node_user -->|"runs export"| node_exporter
node_exporter -->|"reads runs"| node_runlog
node_exporter -->|"reads evals"| node_evalrecords
node_exporter -->|"reads lessons"| node_lessons
node_exporter -->|"reads project metadata"| node_projects
node_exporter -->|"writes package"| node_exportdata

click node_brain "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_projects "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_briefing "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_kos "https://github.com/idikuterke/onoz-brain/blob/master/skills/kos/kos.py"
click node_skilllib "https://github.com/idikuterke/onoz-brain/tree/master/skills"
click node_lessons "https://github.com/idikuterke/onoz-brain/tree/master/memory/lessons"
click node_runlog "https://github.com/idikuterke/onoz-brain/tree/master/memory/runs"
click node_promotion "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_stats "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_evaltasks "https://github.com/idikuterke/onoz-brain/tree/master/evals"
click node_evalrunner "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_evalrecords "https://github.com/idikuterke/onoz-brain/tree/master/memory/evals"
click node_health "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_activity "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_dashboard "https://github.com/idikuterke/onoz-brain/blob/master/brain.py"
click node_exporter "https://github.com/idikuterke/onoz-brain/blob/master/skills/anonim-export/scripts/brain_export.py"

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_brain,node_projects,node_projectrepos,node_briefing,node_kos toneBlue
class node_skilllib,node_lessons toneAmber
class node_runlog,node_promotion,node_stats,node_evaltasks,node_evalrunner,node_evalrecords,node_health,node_activity,node_dashboard toneMint
class node_exporter,node_exportdata toneRose
class node_user,node_agent toneIndigo
```

## Components

### Project workflow

- [Brain CLI](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- [Project registry](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- **Project repositories**
- [Agent briefing](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- [Skill runner](https://github.com/idikuterke/onoz-brain/blob/master/skills/kos/kos.py): `skills/kos/kos.py`

### Skills and evidence

- [Skill library](https://github.com/idikuterke/onoz-brain/tree/master/skills): `skills`
- [Lessons](https://github.com/idikuterke/onoz-brain/tree/master/memory/lessons): `memory/lessons`

### Measurement and oversight

- [Run ledger](https://github.com/idikuterke/onoz-brain/tree/master/memory/runs): `memory/runs`
- [Promotion rules](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- [Run statistics](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- [Eval task sets](https://github.com/idikuterke/onoz-brain/tree/master/evals): `evals`
- [Eval runner](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- [Eval records](https://github.com/idikuterke/onoz-brain/tree/master/memory/evals): `memory/evals`
- [Project health](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- [Commit activity](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`
- [Read-only dashboard](https://github.com/idikuterke/onoz-brain/blob/master/brain.py): `brain.py`

### Data export

- [Anonymous exporter](https://github.com/idikuterke/onoz-brain/blob/master/skills/anonim-export/scripts/brain_export.py): `skills/anonim-export/scripts/brain_export.py`
- **Export package**

### Other components

- **Engineer**
- **External agent**

## Connections

- Engineer → Brain CLI: runs commands (evidence: `README.md`)
- Brain CLI → Project registry: links projects (evidence: `README.md`)
- Project registry → Project repositories: marks project root (evidence: `README.md`)
- Brain CLI → Agent briefing: builds context (evidence: `README.md`)
- Agent briefing → External agent: briefs (evidence: `README.md`)
- External agent → Project repositories: works in (evidence: `README.md`)
- Engineer → Skill runner: runs skill (evidence: `skills/kos/kos.py`)
- Skill runner → Skill library: loads verification (evidence: `skills/kos/kos.py`)
- Skill runner → Project repositories: runs verification (evidence: `skills/kos/kos.py`)
- Skill runner → Brain CLI: invokes log (evidence: `skills/kos/kos.py`)
- Brain CLI → Run ledger: records runs (evidence: `README.md`)
- Engineer → Brain CLI: adds lessons (evidence: `README.md`)
- Brain CLI → Lessons: stores rules (evidence: `README.md`)
- Brain CLI → Run statistics: summarizes runs (evidence: `README.md`)
- Brain CLI → Promotion rules: calculates candidates (evidence: `README.md`)
- Run ledger → Promotion rules: supplies evidence (evidence: `README.md`)
- Engineer → Promotion rules: approves apply (evidence: `README.md`)
- Engineer → Eval runner: runs eval (evidence: `README.md`)
- Eval runner → Eval task sets: selects task (evidence: `README.md`)
- Eval runner → Project repositories: tests project (evidence: `brain.py`)
- Eval runner → Eval records: records results (evidence: `brain.py`)
- Brain CLI → Project health: collects status (evidence: `README.md`)
- Project health → Project repositories: reads git state (evidence: `README.md`)
- Brain CLI → Commit activity: classifies commits (evidence: `README.md`)
- Commit activity → Project repositories: reads commit history (evidence: `README.md`)
- Brain CLI → Read-only dashboard: generates view (evidence: `README.md`)
- Project health → Read-only dashboard: feeds health (evidence: `README.md`)
- Commit activity → Read-only dashboard: feeds activity (evidence: `README.md`)
- Engineer → Anonymous exporter: runs export (evidence: `skills/anonim-export/scripts/brain_export.py`)
- Anonymous exporter → Run ledger: reads runs (evidence: `skills/anonim-export/scripts/brain_export.py`)
- Anonymous exporter → Eval records: reads evals (evidence: `skills/anonim-export/scripts/brain_export.py`)
- Anonymous exporter → Lessons: reads lessons (evidence: `skills/anonim-export/scripts/brain_export.py`)
- Anonymous exporter → Project registry: reads project metadata (evidence: `skills/anonim-export/scripts/brain_export.py`)
- Anonymous exporter → Export package: writes package (evidence: `skills/anonim-export/scripts/brain_export.py`)
