# Brief — brain-compose > Document de préparation à la forge. À lire par `recruiter` avant la session. > Décisions actées en session 2026-03-13 — ne pas re-débattre. --- ## L'intention Le brain est un OS. Jusqu'ici il tournait en mono-instance — une machine, une config, un contexte. C'est suffisant pour commencer. Ce n'est pas suffisant pour grandir. `brain-compose` est la couche qui rend le brain **modulaire** : plusieurs instances du même kernel, chacune avec sa propre config et son propre état, sur une ou plusieurs machines. Ce n'est pas une feature. C'est une architecture. --- ## Le problème qu'il résout ``` Aujourd'hui Avec brain-compose ──────────────────────────────── ────────────────────────────────── 1 machine = 1 brain 1 machine = N brains indépendants 1 contexte à la fois Sessions parallèles possibles Infra hardcodée dans les Sources Config par instance, kernel propre Fork = tout reconfigurer à la main Fork = kernel + config-scribe → opérationnel Pas de portabilité entre machines brain-compose.local.yml = registre machine ``` --- ## L'architecture — trois couches, une règle ``` KERNEL agents/, profil/, templates/ Universel. Partagé entre toutes les instances. Mis à jour une fois → profite à tout le monde. Versionné dans le repo principal. INSTANCE infrastructure/*.md, PATHS.md, projets/, todo/, focus.md Personnel. Propre à chaque instance. Écrit par config-scribe et les scribes métier. Jamais dans le kernel. PERSONNEL progression/, capital.md Intime. Jamais partagé, jamais exporté. Appartient à une personne, pas à un brain. ``` **La règle :** le kernel ne connaît pas les instances. Les instances connaissent le kernel. Dépendance unidirectionnelle. C'est ce qui permet de mettre à jour le kernel sans casser quoi que ce soit en dessous. --- ## Kernel partagé — comment concrètement **Décision actée :** le kernel est partagé, pas dupliqué. ``` ~/Dev/ ├── Docs/ ← kernel + instance perso (brain principal) │ ├── agents/ ← kernel │ ├── profil/ ← kernel │ ├── infrastructure/ ← instance perso (écrit par config-scribe) │ ├── projets/ ← instance perso │ └── PATHS.md ← instance perso │ ├── client-xyz/ ← instance client │ ├── agents/ → symlink vers ~/Dev/Docs/agents/ (kernel partagé) │ ├── profil/ → symlink vers ~/Dev/Docs/profil/ │ ├── infrastructure/ ← config propre (écrit par config-scribe) │ ├── projets/ ← état propre │ └── PATHS.md ← chemins propres │ └── brain-compose.local.yml ← registre de toutes les instances sur cette machine ``` **Pourquoi symlinks plutôt que clones ?** Un `git pull` sur le kernel = toutes les instances à jour instantanément. Pas de sync manuel. Pas de divergence silencieuse. **Limite à documenter :** sur Windows ou certains systèmes de fichiers, les symlinks ont des contraintes. À vérifier lors de la forge. --- ## Les deux fichiers clés ### `brain-compose.yml` — la spec (versionnée dans le kernel) Ce fichier définit ce qu'une instance brain PEUT être. C'est le schema, pas l'état. ```yaml # brain-compose.yml version: "1.0" # Agents disponibles dans ce kernel agents: core: - scribe - coach - recruiter - config-scribe - helloWorld metier: - vps - mail - ci-cd - debug - security - testing - refacto - monitoring - optimizer-backend - optimizer-db - optimizer-frontend - pm2 - migration - frontend-stack - i18n - doc scribes: - todo-scribe - toolkit-scribe - coach-scribe - capital-scribe - git-analyst meta: - orchestrator - agent-review - mentor - interprete - brainstorm # Feature flags — quels agents sont actifs selon le tier features: free: - core - debug pro: - core - metier - scribes full: - core - metier - scribes - meta ``` > Ce fichier est exportable. Il fait partie du `claude-brain-template`. > Il définit les possibilités — `brain-compose.local.yml` définit l'état réel. --- ### `brain-compose.local.yml` — le registre machine (non versionné, gitignored) Ce fichier enregistre les instances actives sur cette machine. ```yaml # brain-compose.local.yml # Ne pas versionner — contient des chemins et configs locaux machine: instances: perso: path: ~/Dev/Docs/ kernel: ~/Dev/Docs/ feature_set: full config_status: hydrated # ou: empty, partial last_setup: 2026-03-13 client-xyz: path: ~/Dev/client-xyz/ kernel: ~/Dev/Docs/ # pointe vers le même kernel feature_set: pro config_status: partial last_setup: ~ active: perso ``` --- ## Les opérations (via l'agent brain-compose) ``` brain-compose new Crée une nouvelle instance : → crée le dossier → symlink vers le kernel → invoque config-scribe pour hydrater la config → ajoute l'entrée dans brain-compose.local.yml brain-compose list Liste toutes les instances avec leur statut brain-compose status [] État d'une instance : → config complète ou placeholders résiduels ? → kernel à jour ? brain-compose sync kernel Met à jour le kernel (git pull) → toutes les instances profitent instantanément brain-compose diff Compare les configs de deux instances → utile avant de migrer un projet d'une instance à l'autre ``` > **Convention plutôt que CLI** : ces opérations sont réalisées par l'agent brain-compose > via Claude Code. Pas d'outil externe à installer. Claude Code est le runtime. --- ## Relation avec config-scribe `brain-compose` et `config-scribe` sont des partenaires, pas des concurrents. ``` brain-compose new │ ├── crée la structure (dossier, symlinks, brain-compose.local.yml) │ └── invoque config-scribe │ └── wizard par catégories → hydrate infrastructure/*.md + PATHS.md → confirme : "Instance opérationnelle" ``` config-scribe ne sait pas qu'il est dans une instance. Il fait son travail. brain-compose orchestre. config-scribe exécute. --- ## Feature gating — la vision produit ``` claude-brain-template (open-source) → brain-compose.yml livré avec feature_set: free → agents core + debug disponibles → les autres agents existent dans le kernel mais ne sont pas invoquables Fork personnel → feature_set: full → tout est disponible, aucune restriction Brain-as-a-Service → feature_set par compte utilisateur → tier free → pro → full selon l'abonnement → brain-compose.yml est le contrat de service ``` > Les agents "bloqués" ne sont pas absents — ils sont dans le kernel. > C'est `brain-compose.yml` qui contrôle l'accès, pas la présence des fichiers. > Même kernel pour tout le monde. Personnalité différente par les feature flags. --- ## Ce qui reste à décider en session forge 1. **Symlinks vs autre mécanisme** — valider que les symlinks tiennent sur toutes les plateformes cibles. Alternative : git submodules, git worktrees. 2. **brain-compose.yml dans CLAUDE.md** — comment helloWorld lit les feature flags pour savoir quels agents proposer au démarrage. 3. **Scope exact de l'agent brain-compose** — agent Claude pur, ou besoin de scripts bash pour créer les symlinks / dossiers ? 4. **Que se passe-t-il si le kernel évolue et casse une instance ?** — stratégie de migration (semver sur brain-compose.yml ?). --- ## Plan de la session forge ``` 1. Recruiter lit ce brief 2. Questions QCM sur les 4 points ouverts ci-dessus 3. Forge brain-compose agent (depuis _template.md enrichi) 4. Mise à jour brain-compose.yml schema si nécessaire 5. Mise à jour config-scribe — ajouter la génération brain-compose.local.yml 6. Scribe → AGENTS.md + CLAUDE.md + todo brain-compose Phase 2 ✅ ``` --- ## Ce qu'on ne fera PAS dans cette session - Écrire du code bash pour les symlinks → documenter le pattern, pas l'implémenter - Décider du modèle économique Brain-as-a-Service → c'est une session séparée - Toucher à helloWorld → découplé, session dédiée --- ## Vision produit — brain CLI (capturée 2026-03-13, à brainstormer) > Ne pas implémenter dans cette session. Capturer l'intention complète. ```bash brain new # crée une instance locale, lance config-scribe # opérationnel SANS connexion — kernel local brain sync -p # prompt password → auth serveur Brain-as-a-Service # valide l'abonnement → renvoie le feature_set # sync contexte distant (progression/, positions, config) # brain-compose.local.yml → tier mis à jour # "Mode actif : pro. 12 agents débloqués." ``` **Ce que ça implique :** - `brain new` = usage local pur, pas de compte requis. Le kernel est local. - `brain sync` = pont entre l'instance locale et le service distant. - Le serveur gère : auth, abonnements, feature_set par compte, sync contexte. - L'instance locale tourne sans connexion — sync = optionnel, pas obligatoire. --- ## Modèle tokens — décision actée (BYOK) **Le service ne gère pas les tokens Claude. TOTO apporte son propre accès Claude.** ``` TOTO → abonnement Claude.ai Pro/Max ou clé API Anthropic (son affaire) TOTO → abonnement Brain-as-a-Service (feature_set + sync) Tokens Claude → 100% sur le compte Claude de TOTO Brain-as-a-Service → vend les features et le sync, pas la puissance de calcul ``` **Ce que Brain-as-a-Service vend :** ``` ✅ Accès aux features selon le tier (feature_set free / pro / full) ✅ Sync du contexte entre machines (progression/, positions, config) ✅ Kernel maintenu et mis à jour ✅ Structure brain prête à l'emploi ❌ Tokens Claude — jamais ❌ Transit de données utilisateur via la clé du service — jamais ``` **Parcours TOTO :** ``` 1. TOTO a Claude.ai Pro (ou clé API Anthropic) 2. TOTO crée un compte Brain-as-a-Service 3. brain sync -p toto → auth Super-OAuth → valide abonnement → renvoie feature_set 4. brain-compose.local.yml → tier mis à jour 5. Tokens Claude → toujours sur le compte de TOTO. Le service n'y touche pas. ``` **Pourquoi BYOK est la seule direction raisonnable :** ``` Risque financier → zéro. Ce n'est pas le service qui paie les tokens de TOTO. Risque légal → zéro. Pas de transit de données via une clé master. Risque technique → zéro. Pas de quota à gérer, pas de billing tokens à implémenter. Marge → 100% prévisible. Abonnement = accès features. Point. ``` **CLI vs convention — réponse finale :** ``` Usage perso (power user) → convention pure + agent Claude. Pas de CLI. Produit distribué → CLI `brain` obligatoire. brain new + brain sync. Les deux coexistent. ``` **L'ironie magnifique :** `brain sync` tourne sur Super-OAuth pour l'auth. Le brain s'authentifie avec l'outil que tu as construit. JWT + Redis + OAuth2 — déjà en prod. La boucle est bouclée. **Prérequis pour cette vision :** - brain-compose agent forgé et stable ✅ (cette session) - config-scribe validé en conditions réelles - Super-OAuth exposé comme fournisseur d'auth externe - Serveur Brain-as-a-Service (API sync + gestion abonnements) - CLI `brain` packagée (npm global ou binaire)