brain-template/README.md

brain-template

Système de coordination multi-instances pour Claude — protocole BSI-v3. Forke ce repo pour démarrer ton propre brain.

---

Ce que c'est

Un brain est un système de contexte persistant et coordonné pour Claude. Chaque session repart d'un état connu. Plusieurs instances peuvent travailler en parallèle sans conflit.

Git (MVCC) + Agents calibrés + Protocole BSI-v3
= Claude qui ne répète pas les mêmes erreurs
  qui coordonne plusieurs instances simultanées
  qui respecte ton périmètre de travail

---

Tiers

Tier	Accès	Activation
free	Kernel complet + BSI-v3 + agents fondamentaux	Fork public — aucune clé
pro	+ Agents métier (code-review, security, vps, ci-cd…)	Clé API tier: pro
full	+ Distillation locale (brain-engine) + instances rendering	Clé API tier: full

Tier free — ce que tu as sans rien demander

Agents : coach, scribe, debug, mentor, helloWorld, brainstorm, orchestrator,
         todo-scribe, interprete, aside, recruiter, agent-review

Protocole BSI-v3 complet :
  - Multi-instances sans conflit (file-lock.sh + preflight-check.sh)
  - Human gate + pause cascade (human-gate-ack.sh)
  - Vue live multi-instances (brain-status.sh)
  - Theme branches + workflows déclarés
  - Tiered-close + exit triggers

Modes brain-compose : prod, dev, brainstorm, coach, debug, HANDOFF…

Tier pro — avec clé API

Agents supplémentaires : code-review, security, testing, refacto,
                         vps, ci-cd, monitoring, pm2, migration,
                         frontend-stack, optimizer-*, toolkit-scribe,
                         coach-scribe, git-analyst, capital-scribe,
                         i18n, doc, mail, config-scribe

→ Ajouter dans brain-compose.yml :
    brain_api_key: bk_live_<ta-clé>

Tier full — avec clé API full

Tout pro +
  - brain-engine en local (distillation 2-pass, résumés compressés)
  - Mode rendering : instances autonomes sur tes projets
  - RAG sur l'historique brain
  - Toutes les optimisations de contexte (BE-*)

→ brain-engine s'installe localement
→ Sans clé valide : brain fonctionne en free, distillation inactive
→ Clé liée à ton fork — non redistribuable

Obtenir une clé : contact@<OWNER_DOMAIN> (beta privée — partage limité)

---

Brain API Key — configuration

Ajouter une clé

# Dans brain-compose.yml — champ déjà présent, remplacer null :
brain_api_key: bk_live_<ta-clé>

# Ou via brain-setup.sh (nouvelle machine) — étape 3.5 le demande automatiquement

La clé est validée au boot par key-guardian (silencieux, timeout 3s) :

• Succès → feature_set mis à jour dans brain-compose.local.yml
• VPS down → grace period 72h depuis dernière validation — tier conservé
• Clé absente/invalide → tier free, aucun blocage, aucune erreur

Format des clés

Format	Usage	Tier
bk_live_<32chars>	Production	pro ou full selon la clé
bk_test_<32chars>	Dev/test local	free forcé (toujours valide)

Tester sans clé

# Clé test — tier free garanti, pas de réseau requis
brain_api_key: bk_test_local_dev_key_xxxxxxxxxxxxxxxx

---

Installation — 15 minutes

Prérequis

• Git
• Claude Code CLI
• Un repo Git (Gitea, GitHub…)

1. Forker le template

git clone git@<TON_GITEA>:<USERNAME>/brain-template.git ~/Dev/Brain
cd ~/Dev/Brain
git remote rename origin upstream   # garder le lien vers les updates kernel
git remote add origin git@<TON_GITEA>:<USERNAME>/mon-brain.git
git push -u origin main

2. Configurer CLAUDE.md

# Copier vers le profil global Claude
cp profil/CLAUDE.md.example ~/.claude/CLAUDE.md

# Éditer ~/.claude/CLAUDE.md :
#   brain_root: /home/<user>/Dev/Brain
#   brain_name: prod

3. Configurer les chemins machine

# Éditer PATHS.md — remplacer les placeholders :
#   <BRAIN_ROOT>     → /home/<user>/Dev/Brain
#   <GITEA_URL>      → git@git.example.com
#   <USERNAME>       → ton username
#   <PROJECTS_ROOT>  → /home/<user>/Dev/Projects

4. Personnaliser brain-compose.local.yml

cp brain-compose.local.yml.example brain-compose.local.yml
# Éditer : kernel_path, instances, [api_key si tier pro/full]

5. Cold boot

Ouvrir Claude Code dans le dossier brain et taper :

Bonjour — démarre le brain (helloWorld)

Signal de succès : contexte posé en < 3 échanges, sans redemander qui tu es.

---

Multi-instances — le protocole

Plusieurs fenêtres Claude Code sur le même brain, sans conflit :

# Fenêtre 1 — coach/discussion
bash scripts/brain-status.sh          # voit tout ce qui se passe

# Fenêtre 2 — travail terrain (ex: projet superoauth/)
# Elle ouvre un claim, pre-flight check avant chaque écriture,
# mutex si fichier partagé → BRAIN-INDEX.md synchronise tout

Guide complet : agents/AGENTS.md — le wiki se construit au fil des sessions.

---

Structure

brain/
├── agents/               ← 63 agents calibrés (index : agents/AGENTS.md)
├── contexts/             ← sessions BSI prédéfinies (navigate, work, pilote…)
├── agent-memory/         ← mémoire persistante agents (README + _template/)
├── scripts/              ← BSI-v3 protocol (index : scripts/README.md)
│   ├── brain-status.sh   ← vue live multi-instances
│   ├── preflight-check.sh← 6 checks avant écriture
│   ├── file-lock.sh      ← mutex fichier
│   ├── human-gate-ack.sh ← gate humain + pause cascade
│   └── ...
├── workflows/            ← chaînes de satellites déclarées
├── locks/                ← registre mutex fichiers (BSI-v3-7)
├── claims/               ← sessions BSI (vide au démarrage)
├── BRAIN-INDEX.md        ← état global — lu par toutes les instances
├── KERNEL.md             ← loi des zones (ne pas modifier seul)
├── brain-compose.yml     ← modes, feature flags, agents autorisés
├── brain-compose.local.yml← config machine (non versionné)
└── PATHS.md              ← chemins machine (à personnaliser)

---

BSI-v3 — protocole de coordination

Le protocole qui permet plusieurs instances sans collision :

Composant	Rôle
claims/*.yml	Chaque session déclare son scope — visible par toutes
BRAIN-INDEX.md	Registre global — état en temps réel
file-lock.sh	Mutex fichier — empêche les écritures simultanées
preflight-check.sh	6 checks avant d'écrire (scope, zone, lock, circuit breaker…)
human-gate-ack.sh	Pause planifiée ou urgence — cascade sur les instances enfants
brain-status.sh	Vue live : qui travaille où, quels fichiers lockés, quels signaux

---

Zones — ce que tu peux modifier

Zone	Contenu	Règle
kernel	agents/ scripts/ KERNEL.md brain-compose.yml	Décision humaine — preflight bloque les agents
project	todo/ workspace/ projets/	Libre — rendering mode ici
personal	profil/capital progression/	Ton contenu, non distribué

---

Recevoir les updates kernel

git fetch upstream
bash scripts/kernel-update-check.sh --remote  # détecte conflits vs updates
# Appliquer les non-conflictuels :
bash scripts/kernel-update-check.sh --remote --apply

kernel.lock — checksums SHA-256 des fichiers kernel. Permet de savoir exactement ce qui a divergé avant de puller.

---

Roadmap

• BSI-v3 multi-instances (v3-1b → v3-8)
• Rendering mode — instances autonomes projet
• kernel.lock + isolation check
• Validation clé API (tier pro/full) — key-guardian + grace 72h
• kernel-orchestrator (v3-9) — routage autonome entre satellites
• brain-engine hosted (distillation managée)

---

Licence

MIT — kernel libre. brain-engine (distillation) non inclus dans ce template.