chore: retirer brief interne brain-compose (document de forge, pas universel)
This commit is contained in:
@@ -1,381 +0,0 @@
|
|||||||
# 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: <nom-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 <nom> 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 [<nom>] É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 <A> <B> 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 <nom>
|
|
||||||
│
|
|
||||||
├── crée la structure (dossier, symlinks, brain-compose.local.yml)
|
|
||||||
│
|
|
||||||
└── invoque config-scribe
|
|
||||||
│
|
|
||||||
└── wizard par catégories → hydrate infrastructure/*.md + PATHS.md
|
|
||||||
→ confirme : "Instance <nom> 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 <pseudo> # 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)
|
|
||||||
Reference in New Issue
Block a user