brain-template/docs/architecture.md

# Architecture du brain

> Comment les pieces s'assemblent. Version humaine — pas la spec technique.

---

## Vue d'ensemble

Le brain c'est 3 couches :

**1. Le kernel** — l'identite
- Les regles qui ne changent pas (KERNEL.md, constitution, PATHS.md)
- Les agents specialises (~75 fichiers .md)
- Le profil de collaboration
- Le brain-compose.yml (config, tiers, modes)

**2. Les satellites** — la memoire
- `todo/` — les intentions et taches
- `progression/` — ta progression, tes skills, ton metabolisme
- `toolkit/` — les patterns valides en prod, reutilisables
- `reviews/` — les audits d'agents
- `profil/` — ton identite, tes objectifs

Chaque satellite est un repo Git independant. Le kernel les ignore (gitignore). Ils vivent leur vie.

**3. L'instance** — le runtime
- `claims/` — quelle session est active, sur quoi
- `workspace/` — les sprints en cours, checkpoints
- `brain-compose.local.yml` — config machine (tier, cle API, peers)
- `brain.db` — base SQLite pour BSI et etat live

---

## Comment une session fonctionne

```
Tu tapes "brain boot mode work/mon-projet"
          |
          v
    helloWorld lit ta config
          |
          v
    Charge le minimum (L0 : kernel + paths + config)
          |
          v
    Lit le manifest de session (contexts/session-work.yml)
          |
          v
    Charge les agents pertinents (L1 : debug, coach-boot, scribe)
          |
          v
    Charge le projet si declare (L2 : projets/mon-projet.md + todo/mon-projet.md)
          |
          v
    Ouvre un claim BSI (trace de session)
          |
          v
    "Pret." → tu travailles
          |
          v
    Tu dis "on wrappe"
          |
          v
    Close sequence : metriques → todos → scribe → coach → BSI close
```

---

## Les 4 couches de chargement

Le brain ne charge pas tout. Il utilise 4 couches, du plus leger au plus complet :

**L0 — Toujours charge** (~5%)

3 fichiers. L'identite du brain. Jamais retire.

**L1 — Selon la session** (~15%)

Les agents et fichiers specifiques au type de session. `work` charge debug + coach. `deploy` charge vps + ci-cd. Deterministe : meme session = meme chargement.

**L2 — Selon le projet** (~10%)

Si tu declares un projet dans ta commande, ses fichiers sont charges. Silencieux si le projet n'existe pas.

**L3 — Sur demande** (0% au boot)

Tout le reste. Tu demandes "Charge l'agent testing" → il arrive. Jamais proactif.

**Resultat** : ~25% du contexte au boot, pas 80%. Le brain demarre vite.

---

## Les zones — qui ecrit ou

Le brain a des zones protegees. Chaque session sait ou elle peut ecrire :

**Zone kernel** — protection maximale

KERNEL.md, CLAUDE.md, agents/, profil/. Aucune modification sans decision humaine. Session `edit-brain` requise.

**Zone satellites** — vie libre

todo/, toolkit/, progression/, reviews/. Les scribes ecrivent librement. Promotion vers le kernel possible.

**Zone instance** — etat runtime

claims/, workspace/, brain.db. Geree automatiquement par les agents systeme.

**Zone projet** — code externe

Ton code, tes repos. Le brain y travaille en session `work`/`debug`/`deploy` mais ne melange jamais avec le kernel.

> Regle : une feature grandit dans un satellite → elle peut etre promue dans le kernel. Le kernel ne derive jamais vers un satellite.

---

## Les tiers — qui a acces a quoi

Le brain a 4 niveaux d'acces. Chaque tier debloque des agents et des sessions :

> 🟢 **free** — le brain fonctionne. Debug, brainstorm, scribes, protection secrets.

> 🔵 **featured** — le brain te connait. Coach complet, distillation RAG, progression.

> 🟠 **pro** — l'atelier complet. Review, securite, tests, deploy, perf, infra.

> 🟣 **full** — ton brain. Modification kernel, pilotage long, supervision.

Detail complet → voir les Vues par tier dans la sidebar.

---

## Les agents — comment ils s'organisent

Chaque agent a un fichier `.md` avec :
- Un **boot-summary** (~25 lignes) — charge au demarrage de session
- Un **detail** (reste du fichier) — charge quand l'agent est actif

Les agents se declenchent automatiquement (domaine detecte) ou sur invocation explicite. Ils se delegent entre eux — chaque agent connait ses limites.

**4 familles :**
- **Metier** — debug, review, securite, tests, refacto, perf, infra
- **Scribes** — scribe, todo-scribe, metabolism-scribe, wiki-scribe
- **Presences** — coach, secrets-guardian, helloWorld, session-orchestrator
- **Systeme** — key-guardian, pre-flight, feature-gate, hypervisor

---

## Multi-instance

Le brain peut tourner sur plusieurs machines et plusieurs sessions en parallele.

- Chaque session a un **claim BSI** — les sessions se voient entre elles
- Les **peers** se declarent dans brain-compose.local.yml
- La **synchronisation** passe par Git (push/pull) et brain.db (SQLite replique)

Si deux sessions veulent ecrire au meme endroit → conflit detecte, resolution humaine.

---

## Pour aller plus loin

- **Detail technique** : wiki/ — session-matrix, context-loading, agents-architecture
- **Agents par famille** : Code & Qualite, Infra & Deploy, Brain & Systeme dans la sidebar
- **Recettes** : Workflows dans la sidebar