From 5841926b2586a9e67641eec12d0763d7210fa471 Mon Sep 17 00:00:00 2001 From: Bruno Charest Date: Sun, 16 Aug 2026 12:31:29 -0400 Subject: [PATCH] docs: roadmap v2 - lecture facilitee (sommaire, legende, quick wins, KPI), 12 axes enrichis (modeles locaux, lab, rapports, couts, favoris, profils), jalons versionnes --- ROADMAP.md | 381 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 381 insertions(+) create mode 100644 ROADMAP.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..182ad5e --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,381 @@ +# đŸ—ș ROADMAP agent-manager — vers le « super outil » + +> **Version du document : 2.0** · Statut : propositions, non engagĂ©es +> Base : analyse du code **v0.2.7** (Rust, 45+ tests, zĂ©ro dĂ©pendance runtime) + +--- + +## 📖 Sommaire + +1. [RĂ©sumĂ© exĂ©cutif](#1--rĂ©sumĂ©-exĂ©cutif) +2. [LĂ©gende de lecture](#2--lĂ©gende-de-lecture) +3. [Quick wins — valeur immĂ©diate](#3--quick-wins--valeur-immĂ©diate) +4. [État des lieux](#4--Ă©tat-des-lieux) +5. [Vision & principes](#5--vision--principes) +6. [Socle technique : le modĂšle de donnĂ©es](#6--socle-technique--le-modĂšle-de-donnĂ©es) +7. [Les 12 axes](#7--les-12-axes) +8. [Jalons versionnĂ©s](#8--jalons-versionnĂ©s) +9. [Indicateurs de succĂšs (KPI)](#9--indicateurs-de-succĂšs-kpi) +10. [Risques & garde-fous](#10--risques--garde-fous) +11. [Par oĂč commencer](#11--par-oĂč-commencer) + +--- + +## 1. 📌 RĂ©sumĂ© exĂ©cutif + +**am** est aujourd'hui un excellent *gestionnaire* d'agents : 72 agents au +catalogue, 9 mĂ©thodes d'installation, dĂ©pendances rĂ©solues automatiquement, +processus pilotĂ©s, REPL avec passerelle shell, sauvegarde export/import. + +Mais il est **aveugle** : il ne retient ni ce qui a Ă©tĂ© fait, ni quand, ni +par quel agent, ni dans quel projet, ni avec quel rĂ©sultat. Les logs sont du +texte libre non interrogeable, l'Ă©tat ne contient que les installations et +le PID courant, l'historique est un simple fichier plat. + +Cette roadmap transforme **am** en **cockpit de votre parc d'agents IA** : + +| RĂŽle | Promesse | PortĂ© par | +|---|---|---| +| 📓 Journal de bord | tout est tracĂ©, rien ne se perd | Axe 1 (journal d'Ă©vĂ©nements) | +| 🔎 RĂ©troviseur | tout est cherchable en 2 secondes | Axes 2, 3, 4 | +| 📊 Tableau de bord | tout est mesurĂ© | Axes 1, 5, 9 | +| đŸ€– Copilote | il pilote Ă  votre place | Axes 6, 7 | + +**Chiffres clĂ©s :** 12 axes · ~55 fonctionnalitĂ©s · 4 jalons (v0.3.0 → v1.0) +· ~15 semaines de travail cumulĂ© · 0 dĂ©pendance runtime ajoutĂ©e. + +--- + +## 2. 📚 LĂ©gende de lecture + +| Symbole | Signification | +|---|---| +| **P0** | Fondations — Ă  dĂ©marrer tout de suite (socle des autres axes) | +| **P1** | Court terme — aprĂšs la phase 0 | +| **P2** | Moyen terme | +| **P3** | Vision — long terme | +| ⭐ | Reprend une demande explicite de l'utilisateur | +| **S** | Effort : moins d'1 jour | +| **M** | Effort : 2 Ă  4 jours | +| **L** | Effort : 1 Ă  2 semaines | +| **XL** | Effort : plus de 2 semaines | +| ⬜ / 🔹 / ✅ | ProposĂ© / En cours / LivrĂ© (rien n'est commencĂ© aujourd'hui) | + +--- + +## 3. ⚡ Quick wins — valeur immĂ©diate + +*Tous en effort S, phase P0, sans dĂ©pendance sur le socle. Livrables en +quelques jours, Ă  caler avant ou pendant la construction du journal.* + +| FonctionnalitĂ© | Commande | Apport | +|---|---|---| +| Voir les logs d'un agent | am logs claude-code (--follow) | tail des logs dĂ©jĂ  Ă©crits par process.rs | +| Filtres sur la liste | am list --running · --sort name,version,status | repĂ©rage instantanĂ© | +| Éditer la config sans Ă©diteur | am config set key value | moins de friction YAML | +| Alias Ă  la volĂ©e | am alias add cc claude-code | sans Ă©diter le fichier | +| Historique propre | dĂ©dup + horodatage de history.txt | base saine pour l'axe 2 | +| Doctor scriptable | am doctor --json | CI et monitoring | +| Ouvrir l'installation | am open claude-code | explorer le rĂ©pertoire de l'agent | +| Version scriptable | am version --json | introspection des scripts | + +--- + +## 4. 🧭 État des lieux (points d'ancrage dans le code) + +| Brique actuelle | Fichier | Limite aujourd'hui | +|---|---|---| +| Catalogue 72 agents, alias, groupes | src/catalog.rs, config.yaml | recherche = sous-chaĂźne stricte, pas de ranking | +| Installation (9 mĂ©thodes), dĂ©pendances OS | src/installers/, src/deps.rs, src/toolchain.rs | solide — rien Ă  redire | +| État local | src/state.rs (state.json v1) | installations + PID courant uniquement, **aucun historique** | +| DĂ©tection externe + cache | src/probe.rs | excellent pattern de cache — Ă  gĂ©nĂ©raliser | +| Processus | src/process.rs | logs non structurĂ©s, pas de sessions, pas de mĂ©triques | +| Journal applicatif | src/output.rs | texte libre horodatĂ©, non interrogeable | +| REPL + passerelle shell | src/repl.rs (history.txt, session_id()) | historique plat, pas de recherche ni de stats | +| Backup | src/commands/export_import.rs | manuel, pas de synchronisation | + +--- + +## 5. 🎯 Vision & principes directeurs + +**Vision :** le cockpit unique du parc d'agents — journal de bord, rĂ©troviseur, +tableau de bord et copilote. + +**Principes :** + +1. **ZĂ©ro dĂ©pendance runtime** — tout est Rust pur et fichiers locaux + (JSONL/JSON), jamais de base de donnĂ©es externe. +2. **Local par dĂ©faut, opt-in pour le distant** — la tĂ©lĂ©mĂ©trie n'existe que + si l'utilisateur l'active ; tout le reste est 100 % local. +3. **Contrats stables** — les sorties --json sont la base des scripts et des + futurs UI : champs ajoutĂ©s, jamais retirĂ©s. +4. **Performance** — Ă©criture en append (JSONL), lectures par fenĂȘtres + temporelles, index dĂ©rivĂ©s rĂ©gĂ©nĂ©rables, caches sur le modĂšle de probe.rs. +5. **Livraison continue** — chaque phase produit un binaire utilisable et + testĂ© ; la barre des 45+ tests monte Ă  chaque jalon. + +--- + +## 6. đŸ§± Socle technique : le modĂšle de donnĂ©es + +*Tout dĂ©pend de ceci. À construire en premier, avant les commandes visibles.* + + state_dir/ + state.json # v2 : + sessions_count, last_used (migration auto depuis v1) + events.jsonl # NOUVEAU — journal d'Ă©vĂ©nements (source de vĂ©ritĂ©) + events-202608.jsonl # rotation mensuelle + sessions.json # NOUVEAU — registre des sessions (index dĂ©rivĂ©) + history/ + .jsonl # NOUVEAU — historique structurĂ© du REPL + projects.json # NOUVEAU — agrĂ©gats par projet (recalculable) + probe-cache.json # existant — pattern de cache Ă  suivre + +| Fichier | RĂŽle | AlimentĂ© par | Reconstruction | +|---|---|---|---| +| events.jsonl | faits bruts (start, stop, run, install
) | process.rs, run_cmd.rs, install_cmd.rs, repl.rs, doctor_cmd.rs | source de vĂ©ritĂ©, jamais reconstruit | +| sessions.json | index des sessions | dĂ©rivĂ© du journal | doctor --fix (rejoue le journal) | +| projects.json | agrĂ©gats par projet | dĂ©rivĂ© du journal | doctor --fix | +| history/*.jsonl | commandes REPL | repl.rs | non (donnĂ©es primaires) | +| state.json v2 | installations + rĂ©sumĂ© | state.rs | partiellement (compteurs depuis le journal) | + +**RĂšgles :** JSONL append-only pour les faits · JSON dĂ©rivĂ©s rĂ©gĂ©nĂ©rables · +migration additive (state v1 reste lisible partout) · doctor --fix rĂ©pare +tout ce qui peut l'ĂȘtre. + +--- + +## 7. đŸ—‚ïž Les 12 axes + +### Axe 1 — 📊 ObservabilitĂ© & statistiques d'utilisation ⭐ + +🎯 Savoir **quoi** a tournĂ©, **quand**, **combien de temps**, avec **quel +taux de succĂšs** — et **combien ça coĂ»te**. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Journal d'Ă©vĂ©nements events.jsonl (toutes les actions de am) | M | P0 | +| am stats + --period 7d/30d/90d + --json (tableaux et barres ASCII) | M | P0 | +| am top — classement des agents par utilisation | S | P1 | +| am log — filtres agent/type/date, --follow | S → M | P0 → P1 | +| am report — rapport hebdo/mensuel en markdown (top agents, Ă©checs, changements) | M | P1 | +| Suivi des coĂ»ts — tokens/€ par session quand l'agent expose son usage (Claude Code --output-format json, Codex
) | M | P2 | +| am monitor — TUI temps rĂ©el : CPU/mĂ©moire par PID, uptime, alertes | L | P2 | +| TĂ©lĂ©mĂ©trie anonyme **opt-in** (compteurs agrĂ©gĂ©s uniquement, jamais de chemins) | M | P3 | + + am stats # vue globale + am stats claude-code --period 30d + am top # qui tourne le plus + am report --last-week # digest markdown + +### Axe 2 — đŸ’Ÿ Historique des commandes ⭐ + +🎯 GĂ©rer, **rechercher** et **rĂ©utiliser** tout ce qui a Ă©tĂ© tapĂ©. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Historique structurĂ© : history/.jsonl (cmd, kind am/shell, cwd, durĂ©e, exit, agent) + migration de history.txt | M | P0 | +| am history — filtres --kind, --cwd, --search, --failed, --session | M | P0 | +| Ctrl-R + !! + !install + !42 + ^old^new dans le REPL | M | P1 | +| am history --rerun 42 (rĂ©exĂ©cution confirmĂ©e) | S | P1 | +| Playbooks : am history 12..25 --save deploy.yaml puis am playbook deploy.yaml | L | P2 | + + am history --search "install" --failed + am history --rerun 42 + +### Axe 3 — 🧭 Projets & workspaces ⭐ + +🎯 Centraliser **quel agent travaille sur quel projet** — automatiquement. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Contexte auto au lancement : racine + branche git, stack dĂ©tectĂ©e (Cargo.toml, package.json
), mis en cache | S | P0 | +| am projects / am projects api — agents, sessions, durĂ©es, derniĂšre activitĂ© | M | P1 | +| Profils de projet dans config : default_agent, env, hooks | M | P1 | +| am start (sans argument) = agent par dĂ©faut du dossier courant ; REPL contextuel | S | P1 | +| am init — gĂ©nĂšre un agent-manager.yaml selon la stack dĂ©tectĂ©e | S → M | P0 | +| Templates : am init --template web | M | P2 | + + am projects + am projects api + am init # dans un projet Node → config prĂ©-remplie + +### Axe 4 — đŸ—‚ïž Sessions centralisĂ©es ⭐ + +🎯 Un registre unique de **toutes les sessions de tous les agents** — +consultable, reprenable, archivable. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| sessions.json + session_id() partagĂ© (repl.rs) ; fin de session avec exit code et durĂ©e | M | P0 | +| RĂ©conciliation au dĂ©marrage : sessions interrompues (crash, reboot) marquĂ©es et datĂ©es | S | P0 | +| am sessions — filtres agent/projet/statut ; show = rĂ©sumĂ© + extrait de log | M | P0 | +| am timeline — vue chronologique unifiĂ©e de toute l'activitĂ© | M | P1 | +| am sessions resume — relance avec les mĂȘmes args/env/cwd | M | P1 | +| am sessions export + rĂ©tention configurable (settings.sessions_retention_days) | M | P2 | + + am sessions --status failed + am sessions show 20260815_143926_a1b2c3 + am timeline --project api + +### Axe 5 — đŸ–„ïž Tableau de bord + +🎯 Voir l'Ă©tat du parc d'un coup d'Ɠil. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| am dashboard — TUI (ratatui/crossterm) : vue d'ensemble, activitĂ© en direct, stats, sessions, projets | L | P1 | +| am web — serveur local + API JSON + page HTML embarquĂ©e avec graphiques | XL | P2 | + +### Axe 6 — đŸ€– Automatisation & orchestration + +🎯 Laisser am **superviser et piloter seul** le parc. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Hooks on_install / on_start / on_stop / on_update (agent, projet, global) — via le runner existant | M | P0 | +| am watch claude-code --restart-on-crash --notify | M | P1 | +| Services : unitĂ©s systemd / plists launchd / tĂąches Windows, am service install claude-code --autostart | L | P2 | +| Planification : am schedule --daily update --all + check santĂ© (cron / Task Scheduler) | M | P2 | +| Orchestration de groupes : ordre, --parallel, attente de santĂ© | L | P2 | +| Conteneurs : profil docker/podman par agent (isolation Ă  la demande) | L | P2 | +| am doctor --watch — vĂ©rifications pĂ©riodiques avec alertes | M | P2 | + +### Axe 7 — 🧠 Intelligence & catalogue + +🎯 Trouver le bon agent, suivre leurs sorties, et comparer. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Recherche fuzzy dans am search (typos, scoring, « vouliez-vous dire ») | M | P1 | +| am compare a b — tableau cĂŽte Ă  cĂŽte (mĂ©thode, deps, catĂ©gorie, activitĂ©) | S | P1 | +| am news — derniĂšres releases des agents installĂ©s (API GitHub/Gitea, cache) | M | P1 | +| Catalogue distant : am catalog update / am catalog add | M | P2 | +| am suggest "un agent pour du Python" — tags + usage rĂ©el | M | P2 | +| am lab — benchmark : mĂȘme tĂąche sur N agents, comparaison durĂ©e/rĂ©sultat/coĂ»t | L | P2 | +| Registre communautaire : publier son catalogue (Gitea) + am registry | L | P3 | +| am ask "installe claude et lance-le" — langage naturel → commande am (fournisseur LLM configurable, optionnel) | L | P3 | + +### Axe 8 — 🔒 SĂ©curitĂ© & gouvernance + +🎯 ProtĂ©ger les secrets, tracer les changements, pouvoir revenir en arriĂšre. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| am secret set OPENAI_KEY --agent claude-code (keyring OS) + injection --env automatique | M | P1 | +| am audit — qui a modifiĂ© quoi quand (checksums des configs, Ă©vĂ©nements) | M | P2 | +| am update --rollback — backup automatique avant chaque mise Ă  jour | M | P2 | +| Politiques : pin de version, settings.update_policy | S | P2 | +| Profils sandbox par agent (commandes/rĂ©pertoires autorisĂ©s) | L | P3 | + +### Axe 9 — 🌐 Multi-machine & collaboration + +🎯 Retrouver son cockpit partout, et le partager. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Synchronisation git automatique : settings.sync_repo, am sync, push Ă  la fermeture du REPL | L | P2 | +| Partage de catalogue d'Ă©quipe : include par URL | S | P2 | +| am migrate — assistant de transfert machine A → B | M | P2 | +| am serve --token — API HTTP + WebSocket pour piloter Ă  distance | XL | P3 | + +### Axe 10 — đŸ§© Confort & personnalisation + +🎯 Adapter am Ă  sa façon de travailler. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Favoris : am favorite / am unfavorite + ⭐ dans am list | S | P1 | +| Notes : am note claude-code "utiliser pour 
" | S | P1 | +| Tags personnels : am tag claude-code python | S | P1 | +| Raccourcis de commandes : settings.shortcuts (i → install, s → start) | S | P1 | +| Profils d'environnement : am profile dev / prod (env + args + agent par profil) | M | P1 | +| ThĂšmes couleurs du REPL | S | P2 | + +### Axe 11 — đŸŽ›ïž ModĂšles locaux + +🎯 Étendre le cockpit aux modĂšles : **ollama, llama.cpp, LM Studio**. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| am models — inventaire : nom, taille disque, quantisation, derniĂšre utilisation | M | P2 | +| Lien agent ↔ modĂšle : am run mon-agent --model llama3.1 | M | P2 | +| doctor vĂ©rifie ollama / llama-server comme n'importe quel outil | S | P2 | +| am models prune — purge des modĂšles inutilisĂ©s | S | P2 | + +### Axe 12 — đŸ› ïž ÉcosystĂšme & expĂ©rience dĂ©veloppeur + +🎯 Rendre am disponible partout et contribuable. + +| FonctionnalitĂ© | Effort | Phase | +|---|---|---| +| Fixtures d'Ă©vĂ©nements rejouables + tests de bout en bout du journal | S | P0 | +| Packaging officiel : winget, scoop, deb/rpm, Homebrew + CI de release | M | P1 | +| ComplĂ©tions dynamiques (agents installĂ©s, groupes personnalisĂ©s) | S | P1 | +| Man pages + documentation gĂ©nĂ©rĂ©e | S | P1 | +| i18n : messages EN/FR | L | P2 | +| Plugin scripts (hooks avancĂ©s, intĂ©gration CI) | M | P2 | + +--- + +## 8. 🚀 Jalons versionnĂ©s + +| Jalon | Version | Contenu principal | DurĂ©e | CritĂšre de sortie | +|---|---|---|---|---| +| **J0 — Fondations** | v0.3.0 | events.jsonl, sessions, am stats, am log, am history, am init, quick wins | ≈ 2 sem | 100 % des actions tracĂ©es · 100+ tests | +| **J1 — Cockpit** | v0.4.0 | recherche fuzzy, Ctrl-R, projects, timeline, dashboard TUI, hooks, secret, favoris, packaging | ≈ 3 sem | retrouver n'importe quelle action passĂ©e en < 2 s | +| **J2 — Automatisation** | v0.5.0 | watch, services, schedule, news/compare, catalogue distant, lab, models, sync | ≈ 4 sem | parc auto-supervisĂ© (crash = redĂ©marrage + alerte) | +| **J3 — Plateforme** | v1.0 | am web, am serve, am ask, registry, tĂ©lĂ©mĂ©trie opt-in, sandbox | ≈ 6 sem | dashboard web complet + API distante | + +--- + +## 9. 📈 Indicateurs de succĂšs (KPI) + +| Indicateur | Cible | +|---|---| +| Part des actions tracĂ©es dans events.jsonl | 100 % dĂšs la v0.3.0 | +| Temps pour retrouver une commande ou session passĂ©e | < 2 s | +| am list Ă  chaud, journal actif | < 100 ms | +| DĂ©pendances runtime ajoutĂ©es | 0 | +| Couverture de tests | ≄ 100 tests en v0.3, +25 par jalon | +| Contrats --json cassĂ©s entre versions mineures | 0 | + +--- + +## 10. ⚠ Risques & garde-fous + +1. **ADN « zĂ©ro runtime »** : toute dĂ©pendance nouvelle est compilĂ©e dans le + binaire, jamais requise Ă  l'exĂ©cution. +2. **Performance** : le journal grossit — fenĂȘtres temporelles, index dĂ©rivĂ©s, + rotation mensuelle, caches façon probe.rs. +3. **Vie privĂ©e** : local par dĂ©faut ; tĂ©lĂ©mĂ©trie opt-in, agrĂ©gĂ©e, anonyme. +4. **Contrats --json** : ajout de champs sans retrait (scripts utilisateurs). +5. **CompatibilitĂ©** : migrations additives ; les exports 0.2.x restent + importables en 0.3+. +6. **ComplexitĂ© UX** : les fonctions avancĂ©es restent derriĂšre + settings.experimental jusqu'Ă  maturitĂ©. +7. **PĂ©rimĂštre** : rester un orchestrateur — ne pas rĂ©implĂ©menter les + fonctionnalitĂ©s propres aux agents (tokens, MCP, prompts), sauf valeur + transversale (stats, sessions, secrets, coĂ»ts). + +--- + +## 11. 🏁 Par oĂč commencer + +*Ordre de construction proposĂ© pour la phase 0 — chaque Ă©tape est un PR +indĂ©pendant et testĂ© :* + +1. **PR 1** — src/events.rs : journal JSONL + rotation + tests. +2. **PR 2** — instrumentation start/stop/run (process.rs, run_cmd.rs). +3. **PR 3** — state.json v2 + migration additive. +4. **PR 4** — sessions.json + am sessions + rĂ©conciliation. +5. **PR 5** — am stats + am log (lecture du journal). +6. **PR 6** — historique structurĂ© + am history (migration de history.txt). +7. **PR 7** — am init + dĂ©tection de contexte (git, stack, cache). +8. **En parallĂšle** — les quick wins de la section 3 (am logs, am list --sort, + am alias add, am config set, am version --json). + +--- + +*Document gĂ©nĂ©rĂ© Ă  partir de l'analyse du code (v0.2.7, commit d886de3). +Chaque item peut ĂȘtre chiffrĂ© et planifiĂ© indĂ©pendamment ; les phases 1 Ă  3 +seront dĂ©taillĂ©es dans des documents dĂ©diĂ©s au moment de leur dĂ©marrage.*