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