feat: brain-engine + brain-ui + docs — template full stack standalone

- brain-engine: server, embed, search, RAG, MCP, start.sh (standalone)
- brain-ui: source React complète, build.sh, DocsView avec tier colors
- docs: 14 pages guides humains (getting-started, architecture, sessions, workflows, agents, vues tier)
- brain-compose.yml v0.9.0: tier featured ajouté, sessions/agents par tier, coach_level, API key schema
- DISTRIBUTION_CHECKLIST v1.2: brain-engine + brain-ui + docs dans la checklist
This commit is contained in:
2026-03-20 20:25:40 +01:00
parent c249d417f5
commit 8244a07881
93 changed files with 12088 additions and 34 deletions

37
docs/README.md Normal file
View File

@@ -0,0 +1,37 @@
# docs/ — Documentation humaine
> Guides lisibles sans contexte brain. Pour forks, onboarding, ou quand tu veux comprendre comment ca marche.
---
## Guides disponibles
| Guide | Description |
|-------|-------------|
| **Guides** | |
| [getting-started.md](getting-started.md) | **Commence ici** — les 5 premieres minutes apres un fork |
| [architecture.md](architecture.md) | Comment les pieces s'assemblent — version humaine |
| [sessions.md](sessions.md) | Types de sessions, permissions, metabolisme, close sequences |
| [workflows.md](workflows.md) | Recettes d'agents — quels agents combiner pour quoi |
| **Agents** | |
| [agents.md](agents.md) | Vue d'ensemble — comparatif tiers, navigation |
| [agents-code.md](agents-code.md) | Agents code & qualite — review, securite, tests, refacto, perf |
| [agents-infra.md](agents-infra.md) | Agents infra & deploy — VPS, CI/CD, monitoring, mail |
| [agents-brain.md](agents-brain.md) | Agents brain & systeme — coach, scribes, orchestration, kernel |
| **Vues par tier** | |
| [vue-tiers.md](vue-tiers.md) | Comparatif — tous les tiers d'un coup d'oeil |
| [vue-free.md](vue-free.md) | 🟢 free — ce que tu as |
| [vue-featured.md](vue-featured.md) | 🔵 featured — ce que tu gagnes |
| [vue-pro.md](vue-pro.md) | 🟠 pro — l'atelier complet |
| [vue-full.md](vue-full.md) | 🟣 full — ton brain, tes regles |
---
## Difference avec wiki/
| Espace | Audience | Contenu |
|--------|----------|---------|
| `docs/` | Humains, forks, onboarding | Guides, explications, FAQ |
| `wiki/` | Agents IA, brain interne | Matrices, specs techniques, lifecycle |
Les deux espaces documentent le meme systeme — `docs/` en langage humain, `wiki/` en reference technique.

170
docs/agents-brain.md Normal file
View File

@@ -0,0 +1,170 @@
# Agents Brain & Systeme
> Les agents qui font vivre le brain — documentation, coaching, orchestration, protection.
---
## Coach — ta progression
### coach
> 🟢 **free** : `coach-boot` (observation legere)
> 🔵 **featured+** : `coach` complet (mentorat, bilans, objectifs)
Le coach est toujours present. Ce qui change selon ton tier :
> 🟢 **free** — Observe en silence. Intervient uniquement sur un risque critique.
> 🔵 **featured** — Bilans de session, objectifs SMART, progression tracee.
> 🟠 **pro** — Idem + contexte projet (review code, patterns, architecture).
> 🟣 **full** — Mentorat long terme — anticipe, challenge les decisions, milestones.
Le coach adapte aussi son comportement au type de session :
- **Silencieux** (navigate, deploy, infra, urgence, audit) — pas de rapport, risque critique uniquement
- **Standard** (work, debug) — actif sur les patterns d'erreur
- **Engage** (brain, brainstorm) — challenge les decisions
- **Complet** (coach, capital) — mentorat structure
- **Copilote** (pilote) — proactif, anticipe
---
## Scribes — la memoire
Les scribes ecrivent pour que rien ne se perde. Chacun a son territoire :
### scribe
> 🟢 **free**
Gardien principal du brain. Met a jour `focus.md`, les fiches projets, l'index des agents. Detecte ce qui est obsolete et le signale.
S'active en fin de session significative (commits, agents forges, decisions prises).
---
### todo-scribe
> 🟢 **free**
Ecrit dans `brain/todo/`. Capture les intentions non realisees, les taches a planifier. Ne priorise pas — il structure et persiste.
---
### metabolism-scribe
> 🟢 **free**
Mesure la sante de chaque session : tokens, duree, commits, context peak. Calcule le `health_score` et le ratio use-brain/build-brain sur 7 jours.
Il ne juge pas — il mesure. Les tendances parlent d'elles-memes.
---
### wiki-scribe
> 🟢 **free**
Maintient la documentation du brain sur deux territoires :
- `wiki/` — reference technique (agents, matrices, specs)
- `docs/` — guides humains (ce que tu lis maintenant)
Route automatiquement : "lisible sans contexte brain ?" → docs, sinon → wiki.
---
### coach-scribe
> 🔵 **featured**
Persiste la progression dans `progression/` : journal de session, competences, milestones. Separe du coach — le coach observe, le scribe ecrit.
---
### toolkit-scribe
> 🟠 **pro**
Capture les patterns valides en prod dans `toolkit/`. Chaque pattern reussi en session devient un template reutilisable.
---
## Orchestration — le systeme nerveux
### helloWorld
> 🟢 **free**
Le majordome. Premier agent au reveil : lit l'etat du systeme, produit le briefing, ouvre le claim BSI, passe la main a session-orchestrator.
---
### session-orchestrator
> 🟢 **free**
Proprietaire du cycle de vie. Decide ce qui est charge au boot, route le travail, declenche les scribes a la fermeture. Ne produit rien — il orchestre.
---
### secrets-guardian
> 🟢 **free**
Surveille les secrets en permanence. Silencieux quand tout va bien — fracassant des qu'une fuite est detectee. Session suspendue, zero exception.
4 surfaces surveillees : code source, chat, commandes shell, outputs d'outils.
---
### brain-guardian
> 🟢 **free**
Auto-mefiance structurelle. Quand le brain travaille sur lui-meme, cet agent exige des preuves pour chaque assertion. Empeche le brain de se convaincre qu'il fonctionne bien sans verification.
---
## Agents systeme — le boot de tous les tiers
> 🟢 **free** — ces agents tournent a chaque boot, quel que soit le tier. Ce sont eux qui font fonctionner le systeme de tiers.
### key-guardian
Valide la Brain API Key au boot. Pas de cle → tier free (silencieux, pas d'erreur). Cle valide → ecrit le tier dans la config. Cache le resultat 24h. VPS down → grace period 72h.
### pre-flight
Gate de boot — verifie que le tier actif autorise la session demandee, que le kerneluser est correct, et que le write_lock est respecte. Bloque si les conditions ne sont pas remplies.
### feature-gate
Feature flags runtime — verifie que chaque agent et session respecte le tier actif. Enforcement silencieux : un agent hors tier n'est pas charge, sans erreur.
---
## Agents kernel — supervision avancee
> 🟣 **full** — supervision pour l'owner du brain
### brain-hypervisor
Supervise les sequences multi-phase. Detecte le drift (quand un workflow derive de son objectif) et intervient.
### kernel-orchestrator
Execute les workflows BSI. Circuit breaker a 3 echecs consecutifs — arret complet, signal humain obligatoire.
---
## Tous les agents de cette page
> 🟢 **free** — `coach-boot` · `scribe` · `todo-scribe` · `metabolism-scribe` · `wiki-scribe` · `helloWorld` · `session-orchestrator` · `secrets-guardian` · `brain-guardian` · `key-guardian` · `pre-flight` · `feature-gate`
> 🔵 **featured** — `coach` (complet) · `coach-scribe`
> 🟠 **pro** — `toolkit-scribe`
> 🟣 **full** — `brain-hypervisor` · `kernel-orchestrator`

112
docs/agents-code.md Normal file
View File

@@ -0,0 +1,112 @@
# Agents Code & Qualite
> Les specialistes qui analysent, reviewent, testent et optimisent ton code.
---
## Review & Securite
### code-review
> 🟠 **pro**
Analyse tout code soumis selon 7 priorites, de la plus critique a la moins urgente :
1. **Securite** — injections, secrets exposes, tokens mal geres
2. **Edge cases** — entrees inattendues, etats limites
3. **Performance** — boucles inutiles, N+1, fuites memoire
4. **Async & erreurs** — promesses, try/catch, rejets non geres
5. **Typage** — pas de `any` sauvage
6. **Clean code** — lisible, maintenable
7. **Obsolescence** — patterns deprecies
Format adaptatif : inline sur un snippet court, rapport structure sur un fichier long.
Si un finding est critique → delegue a `security`. Apres review → suggere `testing`.
---
### security
> 🟠 **pro**
Audite la securite applicative selon 8 priorites :
1. Secrets exposes
2. Auth & tokens (JWT, OAuth2, refresh)
3. Injections (SQL, shell)
4. CSRF / CORS
5. XSS
6. Rate limiting
7. Headers securite
8. Exposition de donnees
Couvre la couche applicative. Pour la couche infra (Apache, SSL, ports) → delegue a `vps`.
---
## Tests
### testing
> 🟠 **pro**
Ecrit les tests et definit la strategie de coverage. Adaptatif :
- **Nouveau code** → TDD : tests d'abord, implementation ensuite
- **Code existant non couvert** → Retroactif : tests sur le comportement constate
- **Refacto prevue** → TDD : les tests guident la refacto
Strategie par couche : tests unitaires purs sur le domaine, mocks sur l'application, integration vraie sur l'infra et les routes.
---
### refacto
> 🟠 **pro**
Restructure le code sans perdre une seule ligne de logique metier. Methode en 5 etapes :
```
1. DIAGNOSTIC — identifier le probleme
2. PLAN — lister les etapes (moins risquee → plus risquee)
3. VALIDATION — confirmer avec toi avant d'agir
4. EXECUTION — une etape a la fois, tests verts a chaque fois
5. VERIFICATION — comportement identique avant/apres
```
3 niveaux de risque : code local (faible) → module (moyen) → architecture (eleve).
Pas de tests existants ? → `testing` les ecrit avant la refacto.
---
## Performance — le trio
> 🟠 **pro** — les 3 agents travaillent en trio ou separement
### optimizer-backend
Perf Node.js — detecte les `await` dans les `forEach`, les fuites memoire, les boucles qui bloquent l'event loop. Suggere `Promise.all`, streams, workers.
### optimizer-db
Perf MySQL — detecte les N+1 (TypeORM), les index manquants, les requetes lentes. Utilise `EXPLAIN` et `slow_query_log`.
### optimizer-frontend
Perf React — detecte les re-renders inutiles, les imports lourds, le lazy loading manquant. Utilise React DevTools Profiler et bundle analyzer.
**Invoquer les 3** pour un audit perf full-stack.
---
## Qui delegue a qui
- `code-review``security` (faille trouvee) · `testing` (couvrir le fix) · `refacto` (structure)
- `security``vps` (infra) · `ci-cd` (secrets pipeline)
- `testing``security` (tests auth) · `code-review` (review des tests)
- `refacto``testing` (tests avant refacto) · `debug` (bugs trouves)
- `optimizer-backend``optimizer-db` (requetes) · `code-review` (qualite)
- `optimizer-db``optimizer-backend` (applicatif) · `vps` (config serveur)
- `optimizer-frontend``ci-cd` (config build)

87
docs/agents-infra.md Normal file
View File

@@ -0,0 +1,87 @@
# Agents Infra & Deploy
> Les specialistes qui deploient, surveillent et maintiennent ton infrastructure.
---
## Deploy & Serveur
### vps
> 🟠 **pro**
Expert de ton VPS — deploie un nouveau service de A a Z :
```
1. Copier le template vhost Apache
2. Activer les modules (proxy, rewrite, headers)
3. Activer le vhost + configtest
4. Pointer le DNS
5. Generer le certificat SSL (Let's Encrypt)
```
Regle non negociable : `apache2ctl configtest` avant chaque reload — un typo = tous les services tombent.
Agit seul sur les actions non destructives. Demande confirmation avant de supprimer un vhost, modifier un container en prod, ou ouvrir un port.
---
### ci-cd
> 🟠 **pro**
Concoit et debug les pipelines CI/CD. Adaptatif par projet :
- **Site statique** → `git pull` uniquement
- **Node.js sans Docker** → `git pull` + `npm ci` + `npm run build`
- **Node.js avec Docker** → `git pull` + `docker compose up -d --build`
- **Config Apache changee** → + `apache2ctl configtest && systemctl reload`
Plateforme : GitHub Actions pour les projets publics, Gitea CI pour le prive.
---
### pm2
> 🟠 **pro**
Process manager Node.js en prod. Gere le cycle de vie des applications (start, restart, logs, monitoring). Intervient quand un process tombe ou consomme trop.
---
### migration
> 🟠 **pro**
Gere les migrations TypeORM — creation, modification, deploiement safe. Verifie que les migrations passent sans perte de donnees et que le rollback est possible.
---
## Surveillance
### monitoring
> 🟠 **pro**
Observabilite — configure les sondes Uptime Kuma, lit les logs VPS, detecte les anomalies. Suggere une sonde apres chaque nouveau deploiement.
---
### mail
> 🟠 **pro**
Specialiste Stalwart (serveur mail). Gere la config SMTP/IMAP, les enregistrements DNS (SPF, DKIM, DMARC), et le diagnostic des problemes de delivrabilite.
VPS gere le serveur, mail gere le protocole.
---
## Qui delegue a qui
- `vps``mail` (Stalwart) · `ci-cd` (pipeline)
- `ci-cd``vps` (config serveur) · `monitoring` (sonde post-deploy)
- `pm2``vps` (si probleme container)
- `migration``debug` (si migration echoue)
- `monitoring``vps` (diagnostic infra)
- `mail``vps` (serveur) · `security` (SPF/DKIM)

91
docs/agents.md Normal file
View File

@@ -0,0 +1,91 @@
# Le brain en 30 secondes
Un brain, c'est un systeme de **specialistes IA** qui travaillent ensemble. Chaque specialiste (agent) fait une chose bien : debugger, reviewer du code, deployer, ecrire des tests. Tu n'en charges jamais plus de 5 a la fois — le brain sait lesquels activer selon ce que tu fais.
Tu forkes le brain, tu codes. Les agents se chargent automatiquement.
---
## Les 4 tiers
> 🟢 **free — Tu forkes, ca marche**
>
> **14 agents + 8 systeme. 6 sessions.** Pas de cle API, pas de config.
>
> Debug, brainstorm, scribes automatiques, protection secrets, creation d'agents custom. Le coach observe en arriere-plan.
> 🔵 **featured — Le brain te connait**
>
> **18 agents + systeme. 8 sessions.** Le coach se reveille.
>
> Bilans de session, objectifs concrets, progression tracee. Le brain se souvient de tes acquis entre sessions grace a la distillation RAG.
> 🟠 **pro — L'atelier complet**
>
> **40 agents + systeme. 12 sessions.** Tu ship en prod.
>
> Code review (7 priorites), audit securite (8 priorites OWASP), tests automatises, 3 optimiseurs perf, deploy VPS + CI/CD + SSL, sessions urgence et infra.
> 🟣 **full — Ton brain, tes regles**
>
> **75 agents (tous). 15 sessions.** Tu es owner.
>
> Modification du kernel, copilotage long (mode pilote), supervision multi-phase (hypervisor), coach proactif qui anticipe.
---
## Ce qui change quand tu montes
> 🟢 → 🔵 **free vers featured**
>
> Le coach passe de spectateur a mentor. Il fait un bilan a chaque session, fixe des objectifs, et trace ta progression. Le brain apprend de toi — il se souvient entre sessions.
> 🔵 → 🟠 **featured vers pro**
>
> Tu recois une equipe complete : review code, audit securite, tests, refacto, 3 optimiseurs perf, deploy prod, monitoring, pipelines CI/CD. Plus besoin d'improviser — le brain fait le travail metier.
> 🟠 → 🟣 **pro vers full**
>
> Tu deviens owner. Tu modifies le brain lui-meme (kernel, agents, profil). Sessions longues en copilote proactif. Supervision multi-phase avec circuit breaker.
---
## Comment ca marche en pratique
**Les agents se chargent tout seuls.** Tu parles de "bug" → `debug` arrive. Tu dis "deploy" → `vps` + `ci-cd` se chargent. Tu peux aussi les appeler :
```
Charge l'agent testing
Charge les agents security et code-review
```
**Ils se delegent entre eux.** Chaque agent connait ses limites :
- `debug` detecte un probleme infra → passe a `vps`
- `code-review` trouve une faille → passe a `security`
- `optimizer-db` voit un probleme Node.js → passe a `optimizer-backend`
**Ils ne chargent que l'essentiel.** Un agent de 200 lignes → ~25 lignes au boot. Le reste se charge quand tu en as besoin.
---
## Explore les agents par famille
**Code & Qualite** — review, securite, tests, refacto, 3 optimiseurs perf
**Infra & Deploy** — VPS, pipelines CI/CD, monitoring, process manager, mail
**Brain & Systeme** — coach, scribes, orchestration, protection, kernel
→ Chaque famille est accessible dans la sidebar.
---
## Nouveautes
| Date | Quoi de neuf |
|------|-------------|
| 2026-03-20 | Agents 87% plus legers au boot |
| 2026-03-20 | Coach adaptatif — 5 comportements selon la session |
| 2026-03-20 | Fermeture fiable — sequence deterministe |
| 2026-03-18 | Auto-mefiance — le brain se verifie quand il s'edite |
| 2026-03-17 | Supervision avancee — hypervisor + circuit breaker |

165
docs/architecture.md Normal file
View File

@@ -0,0 +1,165 @@
# 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

135
docs/getting-started.md Normal file
View File

@@ -0,0 +1,135 @@
# Demarrer avec le brain
> Tu viens de forker. Voici tes 5 premieres minutes.
---
## Etape 1 — Installer
```bash
git clone <ton-fork> ~/Dev/Brain
cd ~/Dev/Brain
```
Si c'est une nouvelle machine, lance le setup complet :
```bash
bash scripts/brain-setup.sh prod ~/Dev/Brain
```
Ca clone les satellites (toolkit, progression, todo, reviews, profil), installe les hooks, et prepare CLAUDE.md.
---
## Etape 2 — Premier boot
Ouvre Claude Code dans le dossier du brain et tape :
```
brain boot
```
C'est tout. Le brain :
1. Lit ta config machine
2. Charge le minimum necessaire (~20% du contexte)
3. Te presente un briefing : etat du systeme, projets actifs, todos
4. Ouvre un claim BSI (trace de session)
5. Te demande ce que tu veux faire
---
## Etape 3 — Travailler
**Tu veux coder sur un projet :**
```
brain boot mode work/mon-projet
```
Le brain charge les agents pertinents (debug, scribe, todo-scribe) et le fichier projet si il existe.
**Tu veux explorer ou reflechir :**
```
brain boot mode brainstorm/sujet
```
Mode libre, pas de livrable attendu. L'agent `brainstorm` challenge tes idees.
**Tu ne sais pas quoi faire :**
```
brain boot
```
Le briefing te montre tes todos, tes projets actifs, et te pose la question. Reponds naturellement — le brain detecte le type de session.
---
## Etape 4 — Fermer proprement
Quand tu as fini :
```
on wrappe
```
Le brain lance la sequence de fermeture :
- Capture les metriques de ta session
- Met a jour tes todos
- Ferme le claim BSI
Ne ferme pas le terminal avant que le claim soit ferme.
---
## Les commandes essentielles
**Boot**
- `brain boot` — demarrage standard
- `brain boot mode <type>` — choisir son mode (work, debug, brainstorm, brain...)
- `brain boot navigate` — mode lecture seule, le plus leger
**En session**
- `Charge l'agent <nom>` — invoquer un agent specifique
- `/btw <question>` — parenthese rapide sans casser le fil
- `checkpoint` — sauvegarder l'etat avant une pause
**Fermeture**
- `on wrappe` ou `fin` — fermeture propre avec metriques
---
## Les 3 choses a savoir
**1. Le brain charge le minimum.** Il ne lit pas tout au demarrage. Il charge ~20-30% du contexte selon ta session et ajoute le reste a la demande. C'est pour ca qu'il demarre vite.
**2. Les agents se chargent tout seuls.** Tu parles de "bug" → l'agent `debug` arrive. Tu dis "deploy" → `vps` + `ci-cd` se chargent. Tu n'as pas besoin de tout connaitre — le brain route.
**3. Les secrets ne passent jamais dans le chat.** Le `secrets-guardian` surveille en permanence. Si un secret apparait accidentellement, la session se suspend. C'est normal — c'est une protection.
---
## Bonus — le dashboard
Le brain a un dashboard web avec tes docs, tes workflows, et une visualisation 3D de ton corpus.
```bash
# Build le dashboard (une seule fois)
bash brain-ui/build.sh
# Lance brain-engine (sert aussi le dashboard)
bash brain-engine/start.sh
# Ouvre dans ton navigateur
# http://localhost:7700/ui/
```
---
## Et apres ?
- **Voir ce que tu as** → Vue d'ensemble (Agents & Tiers) dans la sidebar
- **Comprendre les sessions** → Sessions dans la sidebar
- **Voir les recettes d'agents** → Workflows dans la sidebar
- **Comprendre l'architecture** → Architecture dans la sidebar

224
docs/sessions.md Normal file
View File

@@ -0,0 +1,224 @@
# Guide des sessions — Brain
> Ce guide explique comment fonctionnent les sessions du brain.
> Pour la reference technique complete : `wiki/session-matrix.md`
---
## C'est quoi une session ?
Une session est une conversation avec le brain, du premier message au dernier commit. Chaque session a un **type** qui determine quels agents sont charges, quels fichiers sont accessibles, et ce que le brain peut ecrire.
Le cycle de vie est simple : **boot → work → close**.
- **Boot** : le brain detecte le type de session, charge le contexte minimum necessaire
- **Work** : tu travailles, les agents pertinents sont disponibles
- **Close** : les scribes capturent les metriques, mettent a jour les todos, et ferment le claim BSI
**Le brain demarre toujours en session.** Si tu ne declares pas de type, tu es automatiquement en session `navigate` — la plus legere. C'est le lobby : tu peux regarder autour, poser des questions, et quand tu veux travailler, tu escalades vers le bon type.
---
## Isolation et escalade
Chaque type de session a un perimetre strict. Le brain ne deborde jamais :
- En **navigate** : lecture seule, orientation — pas de code, pas de modification brain
- En **work** : code projet — pas de modification du brain (kernel, agents)
- En **brain** : modification du brain — pas de code projet
- En **edit-brain** : modification kernel — gate humain obligatoire
Si tu demandes quelque chose qui depasse le scope de ta session, le brain te propose d'escalader :
```
"Cette action depasse le scope navigate — brain boot mode work/superoauth pour continuer."
```
Tu confirmes, le brain ferme la session legere et ouvre la bonne. Deux claims dans l'historique, tout est trace.
---
## Les types de sessions
**Coder & produire**
- `work` — Developpement projet → `brain boot mode work/<projet>`
- `debug` — Investigation bug → `brain boot mode debug/<projet>`
- `deploy` — Ship en prod, config VPS → `brain boot mode deploy/<projet>`
- `infra` — Maintenance VPS, monitoring → `brain boot mode infra`
- `urgence` — Production down, hotfix → `brain boot mode urgence`
**Construire le brain**
- `brain` — Travailler sur les agents, todos, focus → `brain boot mode brain`
- `edit-brain` — Modifier le kernel (gate humain) → `brain boot sudo`
- `kernel` — Lire le kernel sans le modifier → `brain boot mode kernel`
- `pilote` — Session longue, copilotage actif → `brain boot mode pilote`
**Explorer & reflechir**
- `brainstorm` — Explorer, challenger, structurer → `brain boot mode brainstorm/<sujet>`
- `navigate` — Vue d'ensemble legere → `brain boot navigate`
- `coach` — Progression, reflexion strategique → `brain boot mode coach`
- `capital` — Bilan, objectifs, CV → `brain boot mode capital`
- `audit` — Analyse lecture seule, rapport → `brain boot mode audit/<projet>`
- `handoff` — Reprendre une session precedente → `brain boot mode handoff/<id>`
---
## Comment ca se lance — les 4 couches
Le brain ne charge pas tout d'un coup. Il utilise 4 couches, comme des pelures d'oignon :
```
L0 — Toujours charge (~5%)
KERNEL.md, PATHS.md, brain-compose.local.yml
→ L'identite du brain. Non negociable.
L1 — Selon le type de session (~10-18%)
Les agents et fichiers specifiques a CE type de session.
→ work charge debug + coach, deploy charge vps + ci-cd, etc.
L2 — Selon le projet (~5-15%)
Si tu declares un projet dans ta commande, ses fichiers sont charges.
→ projets/<nom>.md + todo/<nom>.md
L3 — Sur demande (0% au boot)
Tout le reste. Charge en cours de session si tu en as besoin.
→ "Charge l'agent testing" → L3 → disponible
```
**Resultat** : ~20-30% du contexte utilise au boot, au lieu de 80%. La session demarre vite.
---
## Ce que chaque session peut / ne peut pas faire
**Sessions projet** — ecrivent dans le code, pas dans le brain :
- `work` · `debug` · `deploy` · `infra` · `urgence` — ecriture projet uniquement
**Sessions brain** — ecrivent dans le brain, pas dans le code :
- `brain` — agents, profil (gate humain sur le kernel)
- `edit-brain`**ecriture kernel autorisee** (gate humain obligatoire)
- `kernel` — lecture seule, aucune ecriture
**Sessions mixtes** :
- `pilote` — ecriture projet + brain (gates architecturaux sur les forks irreversibles)
**Sessions legeres** — ecriture limitee ou aucune :
- `brainstorm` — todo seulement
- `navigate` — aucune ecriture
- `coach` — progression seulement
- `capital` — profil seulement
- `audit` — rapport seul
- `handoff` — herite du handoff
---
## Ce qui se passe quand tu fermes une session
Quand tu dis `fin`, `on wrappe` ou `c'est bon`, le brain lance une sequence de fermeture automatique :
```
1. Metriques → metabolism-scribe capture tokens, duree, commits, health_score
2. Todos → todo-scribe ferme les ✅ et capture les nouveaux ⬜
3. Wiki → wiki-scribe ajoute les nouveaux termes si besoin
4. Brain update → scribe met a jour focus, projets, agents si changement
5. Coach → rapport de session (sauf en navigate, deploy, infra, urgence, audit)
6. BSI close → le claim est ferme, la session est tracee
```
**Pas toutes les etapes a chaque fois.** Le brain adapte selon le type de session :
- **navigate** : juste metriques + BSI close (session legere)
- **work** : metriques + todos + scribe + coach + BSI close (session complete)
- **brainstorm** : metriques + todos emerges + BSI close (pas de commit attendu)
- **pilote** : tout — metriques + todos + wiki + scribe + coach + BSI close
Le coach ne fait pas de rapport en session silencieuse (navigate, deploy, infra, urgence, audit) — il n'intervient que si risque critique.
---
## Le metabolisme — ce qu'on mesure
A la fin de chaque session, le `metabolism-scribe` capture des metriques :
- **tokens_used** : combien de tokens consommes
- **context_peak** : pic d'utilisation du contexte (%)
- **duration_min** : duree de la session
- **commits** : nombre de commits produits
- **todos_closed** : todos coches pendant la session
- **health_score** : score calcule — se lit en tendance sur 7 jours
Le score n'est pas un jugement. Il detecte les patterns :
- Score bas + context haut = session qui consomme sans produire
- Score bas sur un brainstorm = normal (pas de livrable attendu)
- Ratio use-brain/build-brain < 0.5 sur 7j = trop de travail sur le brain, pas assez de production
### Les 3 profils de scoring
Toutes les sessions ne se mesurent pas pareil :
| Profil | Sessions | Ce qui compte |
|--------|----------|--------------|
| **Productif** | work, deploy, debug, infra, urgence | Todos fermes, commits |
| **Constructif** | brain, edit-brain, kernel, pilote | Fichiers kernel touches, ADRs |
| **Exploratoire** | brainstorm, navigate, coach, capital, handoff, audit | Insights captures, duree |
---
## Les tiers
Le brain a un systeme de tiers qui controle l'acces aux agents et aux sessions :
> 🟢 **free** — 6 sessions (work, debug, brainstorm, brain, navigate, handoff). Pas de cle API. Le brain fonctionne quand meme.
> 🔵 **featured** — +2 sessions (coach, capital). Progression personnelle, RAG, coaching complet.
> 🟠 **pro** — +4 sessions (audit, deploy, infra, urgence). Tous les agents metier : code-review, security, vps, ci-cd, monitoring.
> 🟣 **full** — +3 sessions (kernel, edit-brain, pilote). Tous les agents, acces kernel complet, owner du brain.
→ Detail complet : voir **Agents & Tiers** dans la sidebar.
---
## FAQ
### Comment creer un nouveau type de session ?
1. Creer `contexts/session-<type>.yml` avec le format L0/L1/L2/L3
2. Declarer le tier_required et le context_target
3. Ajouter le type dans `brain-compose.yml` > `feature_sets` > le bon tier
4. Ajouter le handoff_default dans `manifest.yml`
5. Ajouter la zone access dans `KERNEL.md`
6. Mettre a jour `wiki/session-matrix.md`
### Comment escalader depuis navigate ?
Dis simplement `brain boot mode <type>` (ex: `brain boot mode work/superoauth`). Le brain ferme navigate et ouvre la session demandee. Tu peux aussi decrire ce que tu veux faire — le brain detectera le debordement et proposera le bon type.
### Pourquoi ma session est en mode conserve ?
Le mode conserve se declenche quand :
- Le contexte depasse 70% ET le health_score est < 1.0
- Le contexte a la fermeture depasse 60%
- C'est une session urgence (conserve automatique)
En mode conserve, le brain cible < 40% de contexte et ne charge que l'essentiel.
### C'est quoi un handoff ?
Un handoff est un fichier qui capture l'etat d'une session pour qu'une autre puisse reprendre. Niveaux :
- **NO** : pas de handoff — la prochaine session repart de zero (cold start)
- **SEMI** : Layer 0 + position
- **SEMI+** : SEMI + focus + projet
- **FULL** : tout le contexte de reprise
---
## Liens
- **Reference technique** : `wiki/session-matrix.md` — matrice complete avec tous les champs
- **Cycle de vie** : `wiki/session-lifecycle.md` — boot → work → close en detail
- **Context loading** : `wiki/context-loading.md` — architecture BHP L0-L3
- **Metabolisme** : `profil/metabolism-spec.md` — formules et seuils

41
docs/vue-featured.md Normal file
View File

@@ -0,0 +1,41 @@
# 🔵 featured — Ce que tu as
> 🔵 **18 agents + systeme. 8 sessions. Le brain te connait.**
Tu as tout ce qui est en free, plus :
---
## Sessions ajoutees
- `coach` — progression, reflexion strategique
- `capital` — bilan professionnel, objectifs, CV
---
## Agents ajoutes
- `coach` (complet) — remplace `coach-boot`. Bilans de session, objectifs SMART, progression tracee.
- `coach-scribe` — persiste la progression (journal, skills, milestones)
- `capital-scribe` — transforme tes milestones en formulations CV
- `progression-scribe` — suivi progression detaille
---
## Capacite debloquee
> 🔵 **Distillation RAG** — le brain enrichit son contexte a chaque session. Il se souvient de tes acquis entre sessions. Plus tu l'utilises, mieux il te connait.
---
## Coach
> 🔵 Bilans de session, objectifs concrets, progression tracee dans `progression/`. Le coach passe de spectateur a mentor.
---
## Ce que tu n'as pas encore
> 🟠 **pro** te donne : code-review (7 priorites), security (8 audits OWASP), testing, refacto, 3 optimiseurs perf, deploy VPS + CI/CD, monitoring, sessions urgence/infra.
→ Detail : voir la vue par tier dans la sidebar.

69
docs/vue-free.md Normal file
View File

@@ -0,0 +1,69 @@
# 🟢 free — Ce que tu as
> 🟢 **14 agents invocables + 8 systeme. 6 sessions. Pas de cle, pas de config.**
---
## Sessions
- `navigate` — orientation, vue d'ensemble
- `work` — developpement projet
- `debug` — investigation bug
- `brainstorm` — explorer, challenger, structurer
- `brain` — travailler sur le brain lui-meme
- `handoff` — reprendre une session precedente
---
## Agents invocables
**Travailler**
- `debug` — methode 5 etapes, bugs locaux et prod
- `mentor` — explications pedagogiques, garde-fou
- `brainstorm` — exploration et structuration de decisions
- `orchestrator` — coordination multi-agents
- `interprete` — clarification d'intention, scope drift
**Maintenir le brain**
- `scribe` — maintenance brain (focus, projets, agents)
- `todo-scribe` — persistance intentions (brain/todo/)
- `recruiter` — creer de nouveaux agents specialises
- `agent-review` — auditer le systeme d'agents
- `brain-guardian` — auto-mefiance quand le brain s'edite
- `aside` — parenthese /btw en session
- `pattern-scribe` — detection patterns recurrents
- `time-anchor` — conscience temporelle, recontextualisation
---
## Agents systeme
Ces agents tournent a chaque boot, quel que soit le tier :
- `helloWorld` — briefing, claim BSI
- `coach-boot` — observation legere, risque critique uniquement
- `secrets-guardian` — surveillance secrets permanente
- `session-orchestrator` — lifecycle boot → work → close
- `metabolism-scribe` — metriques de session
- `wiki-scribe` — documentation wiki/ + docs/
- `key-guardian` — validation API key (absent → free silencieux)
- `pre-flight` — verification tier/session avant chargement
- `feature-gate` — enforcement tiers runtime
---
## Coach
> 🟢 Observe en arriere-plan. Intervient uniquement sur un risque critique. Pas de bilan, pas d'objectifs.
---
## Ce que tu n'as pas encore
> 🔵 **featured** te donne : coach complet avec bilans + objectifs, distillation RAG (le brain se souvient), suivi de progression.
> 🟠 **pro** te donne : review code, audit securite, tests, deploy prod, 3 optimiseurs perf, monitoring.
→ Detail : voir la vue par tier dans la sidebar.

65
docs/vue-full.md Normal file
View File

@@ -0,0 +1,65 @@
# 🟣 full — Ce que tu as
> 🟣 **75 agents (tous). 15 sessions. Tu es owner.**
Tu as tout ce qui est en pro, plus : tous les agents restants.
---
## Sessions ajoutees
- `kernel` — lecture seule du kernel (audit, diagnostic)
- `edit-brain` — modification kernel (gate humain obligatoire)
- `pilote` — co-construction longue, copilotage proactif
---
## Agents ajoutes (selection)
**Supervision**
- `brain-hypervisor` — supervision multi-phase, drift detection
- `kernel-orchestrator` — workflows BSI, circuit breaker
**Contenu**
- `content-orchestrator` — detecte les signaux content, active les agents
- `content-strategist` — strategie YouTube, angle, audience
- `scriptwriter` — scripts video (short 60s + long 12min)
- `seo-youtube` — SEO + thumbnail brief
**Conception**
- `game-designer` — mecanique, equilibrage, progression
- `product-strategist` — business model, monetisation
- `spec-scribe` — specs techniques structurees
**Orchestration avancee**
- `supervisor` — coordination dual-agent, CHECKPOINT
- `context-broker` — cycle respiratoire de contexte
- `satellite-boot` — boot loader pour instances satellites
- `workflow-auditor` — retrospective workflow, KPIs
- `diagram-scribe` — dashboard workflow live
---
## Capacites debloquees
> 🟣 **Ecriture kernel** — modifier KERNEL.md, CLAUDE.md, agents/ (gate humain obligatoire a chaque modification)
> 🟣 **Mode pilote** — copilotage proactif sur sessions longues. Le coach anticipe les bifurcations.
> 🟣 **Distillation L2** — coaching long terme avec contexte accumule (BACT). Le coach connait ton historique complet.
---
## Coach
> 🟣 Mentorat long terme. Anticipe les bifurcations, challenge les decisions, milestones sur plusieurs mois. Le coach connait ton historique complet.
---
## Tu as tout
C'est ton brain. Tu peux modifier n'importe quel agent, forger les tiens, restructurer le kernel. Le seul gate c'est toi — confirmation humaine obligatoire sur les modifications kernel.

65
docs/vue-pro.md Normal file
View File

@@ -0,0 +1,65 @@
# 🟠 pro — Ce que tu as
> 🟠 **40 agents + systeme. 12 sessions. Tu ship en prod.**
Tu as tout ce qui est en featured, plus :
---
## Sessions ajoutees
- `audit` — analyse lecture seule, rapport qualite/secu
- `deploy` — deploiement prod, config VPS
- `infra` — maintenance VPS, monitoring
- `urgence` — incident prod, hotfix critique
---
## Agents ajoutes
**Code & Qualite**
- `code-review` — review selon 7 priorites de vigilance
- `security` — audit OWASP, 8 priorites
- `testing` — tests Jest/Vitest, strategie par couche DDD
- `refacto` — restructuration en 5 etapes, 3 niveaux de risque
- `frontend-stack` — architecture frontend, stack, libs UI
**Performance — le trio**
- `optimizer-backend` — perf Node.js (async, memoire, event loop)
- `optimizer-db` — perf MySQL (N+1, index, EXPLAIN)
- `optimizer-frontend` — perf React (re-renders, bundle, lazy loading)
**Infra & Deploy**
- `vps` — deploy Docker + Apache + SSL de A a Z
- `ci-cd` — pipelines GitHub Actions / Gitea CI
- `monitoring` — sondes Uptime Kuma, alertes, logs
- `pm2` — process manager Node.js prod
- `mail` — Stalwart, DNS, SMTP/IMAP
- `migration` — TypeORM migrations safe
**Documentation & Outils**
- `i18n` — internationalisation, audit traductions
- `doc` — README, API Swagger
- `toolkit-scribe` — capture patterns valides → toolkit/
- `git-analyst` — historique git semantique
- `brain-compose` — gestion multi-instances
- `config-scribe` — configuration brain
- `audit` — diagnostic coherence brain
---
## Coach
> 🟠 Idem featured + contexte projet. Le coach connait ta stack et tes patterns.
---
## Ce que tu n'as pas encore
> 🟣 **full** te donne : ecriture kernel, mode pilote (copilotage long), supervision multi-phase, contenu YouTube pipeline, game design, distillation L2.
→ Detail : voir la vue par tier dans la sidebar.

172
docs/vue-tiers.md Normal file
View File

@@ -0,0 +1,172 @@
# Vue par tier
> Meme agents, autre angle. Ici tu vois tout ce qui est disponible a TON niveau.
> Pour la vue par specialite → Code & Qualite, Infra & Deploy, Brain & Systeme dans la sidebar.
---
## 🟢 free — Ce que tu as
> 🟢 **14 agents invocables + 8 systeme. 6 sessions.**
### Sessions
- `navigate` — orientation, vue d'ensemble
- `work` — developpement projet
- `debug` — investigation bug
- `brainstorm` — explorer, challenger, structurer
- `brain` — travailler sur le brain lui-meme
- `handoff` — reprendre une session precedente
### Agents invocables
**Travailler**
- `debug` — methode 5 etapes, bugs locaux et prod
- `mentor` — explications pedagogiques, garde-fou
- `brainstorm` — exploration et structuration de decisions
- `orchestrator` — coordination multi-agents
- `interprete` — clarification d'intention, scope drift
**Maintenir le brain**
- `scribe` — maintenance brain (focus, projets, agents)
- `todo-scribe` — persistance intentions (brain/todo/)
- `recruiter` — creer de nouveaux agents specialises
- `agent-review` — auditer le systeme d'agents
- `brain-guardian` — auto-mefiance quand le brain s'edite
- `aside` — parenthese /btw en session
- `pattern-scribe` — detection patterns recurrents
- `time-anchor` — conscience temporelle, recontextualisation
### Agents systeme (tournent a chaque boot)
- `helloWorld` — briefing, claim BSI
- `coach-boot` — observation legere, risque critique uniquement
- `secrets-guardian` — surveillance secrets permanente
- `session-orchestrator` — lifecycle boot → work → close
- `metabolism-scribe` — metriques de session
- `wiki-scribe` — documentation wiki/ + docs/
- `key-guardian` — validation API key (absent → free silencieux)
- `pre-flight` — verification tier/session avant chargement
- `feature-gate` — enforcement tiers runtime
### Coach
> 🟢 Observe en arriere-plan. Intervient uniquement sur un risque critique. Pas de bilan, pas d'objectifs.
---
## 🔵 featured — Ce que tu gagnes
> 🔵 **Tout ce qui est en free, plus :**
### Sessions ajoutees
- `coach` — progression, reflexion strategique
- `capital` — bilan professionnel, objectifs, CV
### Agents ajoutes
- `coach` (complet) — remplace `coach-boot`. Bilans de session, objectifs SMART, progression tracee.
- `coach-scribe` — persiste la progression (journal, skills, milestones)
- `capital-scribe` — transforme tes milestones en formulations CV
- `progression-scribe` — suivi progression detaille
### Capacite debloquee
- **Distillation RAG** — le brain enrichit son contexte a chaque session. Il se souvient de tes acquis.
### Coach
> 🔵 Bilans de session, objectifs concrets, progression tracee dans `progression/`. Le coach passe de spectateur a mentor.
---
## 🟠 pro — Ce que tu gagnes
> 🟠 **Tout ce qui est en featured, plus :**
### Sessions ajoutees
- `audit` — analyse lecture seule, rapport qualite/secu
- `deploy` — deploiement prod, config VPS
- `infra` — maintenance VPS, monitoring
- `urgence` — incident prod, hotfix critique
### Agents ajoutes
**Code & Qualite**
- `code-review` — review selon 7 priorites de vigilance
- `security` — audit OWASP, 8 priorites
- `testing` — tests Jest/Vitest, strategie par couche DDD
- `refacto` — restructuration en 5 etapes, 3 niveaux de risque
- `optimizer-backend` — perf Node.js (async, memoire, event loop)
- `optimizer-db` — perf MySQL (N+1, index, EXPLAIN)
- `optimizer-frontend` — perf React (re-renders, bundle, lazy loading)
- `frontend-stack` — architecture frontend, stack, libs UI
**Infra & Deploy**
- `vps` — deploy Docker + Apache + SSL de A a Z
- `ci-cd` — pipelines GitHub Actions / Gitea CI
- `monitoring` — sondes Uptime Kuma, alertes, logs
- `pm2` — process manager Node.js prod
- `mail` — Stalwart, DNS, SMTP/IMAP
- `migration` — TypeORM migrations safe
**Documentation & Outils**
- `i18n` — internationalisation, audit traductions
- `doc` — README, API Swagger
- `toolkit-scribe` — capture patterns valides → toolkit/
- `git-analyst` — historique git semantique
- `brain-compose` — gestion multi-instances
- `config-scribe` — configuration brain
- `audit` — diagnostic coherence brain
### Coach
> 🟠 Idem featured + contexte projet. Le coach connait ta stack et tes patterns.
---
## 🟣 full — Ce que tu gagnes
> 🟣 **Tout ce qui est en pro, plus : tous les agents restants.**
### Sessions ajoutees
- `kernel` — lecture seule du kernel (audit, diagnostic)
- `edit-brain` — modification kernel (gate humain obligatoire)
- `pilote` — co-construction longue, copilotage proactif
### Agents ajoutes (selection)
**Supervision**
- `brain-hypervisor` — supervision multi-phase, drift detection
- `kernel-orchestrator` — workflows BSI, circuit breaker
**Contenu**
- `content-orchestrator` — detecte les signaux content, active les agents
- `content-strategist` — strategie YouTube, angle, audience
- `scriptwriter` — scripts video (short 60s + long 12min)
- `seo-youtube` — SEO + thumbnail brief
**Conception**
- `game-designer` — mecanique, equilibrage, progression
- `product-strategist` — business model, monetisation
- `spec-scribe` — specs techniques structurees
**Orchestration avancee**
- `supervisor` — coordination dual-agent, CHECKPOINT
- `context-broker` — cycle respiratoire de contexte
- `satellite-boot` — boot loader pour instances satellites
- `workflow-auditor` — retrospective workflow, KPIs
- `diagram-scribe` — dashboard workflow live
### Capacites debloquees
- **Ecriture kernel** — modifier KERNEL.md, CLAUDE.md, agents/ (gate humain)
- **Mode pilote** — copilotage proactif sur sessions longues
- **Distillation L2** — coaching long terme avec contexte accumule (BACT)
### Coach
> 🟣 Mentorat long terme. Anticipe les bifurcations, challenge les decisions, milestones sur plusieurs mois. Le coach connait ton historique complet.

207
docs/workflows.md Normal file
View File

@@ -0,0 +1,207 @@
# Workflows — les recettes d'agents
> Quels agents combiner, pour quel resultat. Les combinaisons testees et validees.
---
## Quotidien
### Coder sur un projet
```
brain boot mode work/mon-projet
```
> 🟢 **free**
Agents actifs : `debug`, `scribe`, `todo-scribe`. Le brain detecte ce que tu fais et charge les agents supplementaires si besoin.
---
### Debugger un bug
```
brain boot mode debug/mon-projet
```
> 🟢 **free**
Agent principal : `debug` — methode en 5 etapes (reproduire → isoler → hypotheses → verifier → corriger). Si le bug touche l'infra → delegue a `vps`.
---
### Explorer une idee
```
brain boot mode brainstorm/sujet
```
> 🟢 **free**
Agent principal : `brainstorm` — avocat du diable, challenge tes decisions. Pas de livrable attendu — les insights sont captures en todo si actionnable.
---
## Avant de shipper
### Review code + securite
```
Charge les agents code-review et security
```
> 🟠 **pro**
`code-review` analyse selon 7 priorites. Si un finding critique est detecte → `security` prend le relais pour l'audit OWASP. Apres → `testing` pour couvrir les corrections.
**Recette complete avant prod :**
```
Charge les agents security, code-review et testing
```
Les 3 travaillent en sequence : securite → qualite → tests.
---
### Audit perf full-stack — le trio
```
Charge les agents optimizer-backend, optimizer-db et optimizer-frontend
```
> 🟠 **pro**
Le trio Riri Fifi Loulou :
- `optimizer-backend` — async, memoire, event loop Node.js
- `optimizer-db` — N+1, index manquants, EXPLAIN
- `optimizer-frontend` — re-renders, bundle, lazy loading
Chacun sait ce qu'il ne couvre pas et delegue aux deux autres.
---
## Deploy
### Deployer un nouveau service
```
brain boot mode deploy/mon-projet
```
> 🟠 **pro**
Agents actifs : `vps` + `ci-cd`. Le workflow :
1. `vps` deploie le service (Docker + Apache + SSL)
2. `ci-cd` cree le pipeline (GitHub Actions ou Gitea CI)
3. `monitoring` suggere une sonde post-deploy
---
### Deployer un service mail
```
brain boot mode deploy
Charge les agents vps et mail
```
> 🟠 **pro**
`vps` gere le serveur (container Stalwart, vhost Apache), `mail` gere le protocole (SMTP, IMAP, DNS, SPF, DKIM).
---
## Refacto
### Refacto securisee
```
Charge les agents refacto et testing
```
> 🟠 **pro**
1. `testing` ecrit les tests avant la refacto (filet de securite)
2. `refacto` restructure par etapes (tests verts a chaque etape)
3. `code-review` valide le resultat
**Regle :** pas de tests → pas de refacto niveau 2/3.
---
## Incidents
### Bug en prod
```
brain boot mode urgence
```
> 🟠 **pro**
Agents actifs : `debug` + `vps`. Mode conserve automatique (economie de contexte). `debug` isole le probleme, `vps` intervient si c'est infra.
---
### Incident complexe
```
brain boot mode urgence
Charge les agents monitoring, vps et debug
```
> 🟠 **pro**
`monitoring` lit les alertes et logs → `vps` diagnostique l'infra → `debug` isole le bug applicatif. Sequence : alertes → infra → code.
---
## Brain
### Forger un nouvel agent
```
brain boot mode brain
Charge l'agent recruiter
```
> 🟢 **free**
`recruiter` concoit l'agent : domaine, perimetre, composition, anti-hallucination. Il produit le fichier `.md` complet. `agent-review` peut ensuite l'auditer.
---
### Auditer le systeme d'agents
```
brain boot mode brain
Charge l'agent agent-review
```
> 🟢 **free**
`agent-review` detecte les gaps, les overlaps, et les agents qui ne font pas ce qu'ils promettent. Si un gap est trouve → `recruiter` forge l'agent manquant.
---
### Session pilote (copilotage long)
```
brain boot mode pilote
```
> 🟣 **full**
Le coach est proactif — il anticipe les bifurcations et challenge les decisions. Tous les scribes sont actifs. Contexte max (~35%).
---
## Les combos par tier
> 🟢 **free** — debug seul, brainstorm seul, forger des agents, auditer le systeme
> 🔵 **featured** — tout ce qui est free + sessions coach avec bilans et objectifs
> 🟠 **pro** — review + securite + tests, trio perf, deploy complet, incidents, refacto securisee
> 🟣 **full** — pilotage long, supervision multi-phase, contenu YouTube, modification kernel