agent-manager/ROADMAP.md

# 🗺️ ROADMAP agent-manager — vers le « super outil »

> **Version du document : 3.0** · Statut : phases 0 à 3 livrées
> (v0.3.0 → v1.0.1), maintenance v1.0.2 → v1.1.0
> Base : analyse du code **v0.2.7** (Rust, 45+ tests, zéro dépendance runtime)
>
> ✅ **Phase 0 livrée en v0.3.0 (2026-08-17)** : issues #2 à #16 clôturées,
> 157 tests, release publiée sur Gitea. Les découpages des phases 1 à 3 sont
> en place sur Gitea (issues #25 à #80) : v0.4.0, v0.5.0, v1.0.
>
> ✅ **Phase 1 livrée en v0.4.1 (2026-08-17)** : 17/17 issues clôturées
> (#26–#42), 240+ tests. v0.4.0 a livré 13/17 (#26–#32, #34–#38) ; v0.4.1
> complète avec le dashboard TUI (#33), les favoris/notes/tags (#39), les
> profils d'environnement (#40), les complétions dynamiques + man pages
> (#41) et le packaging officiel + CI (#42). Binaires Windows/Linux publiés
> sur Gitea — am self-update et les installateurs servent la v0.4.1.
>
> ✅ **Phase 2 livrée en v0.6.0 (2026-08-19)** : 28/28 issues clôturées
> (#47–#75), 250+ tests. am web, i18n, services, schedule, lab, sync,
> migrate, models, plugins d'événements… Binaires publiés sur Gitea.
>
> ✅ **Phase v0.7.0 livrée (2026-08-19)** : 5/5 issues clôturées (#88–#92) —
> registre de providers LLM (am providers), secrets partagés par provider,
> flags --provider/--model/--no-config à l'install, configuration
> post-install (bloc config:).
>
> ✅ **Phase 3 livrée en v1.0.0 (2026-08-20)** : 5/5 issues clôturées
> (#76–#80) — télémétrie opt-in, am registry, am ask, profils sandbox,
> am serve (API HTTP + WebSocket). v1.0.1 : self-update décompresse les
> archives, prompt REPL avec shell actif.
>
> 🔧 **Maintenance v1.0.3 (2026-08-20)** : commandes REPL ask/serve/registry
> routées vers am (v1.0.2) ; détection externe corrigée — champ `detect`
> (sonde PATH explicite) pour les lanceurs interpréteurs (npx/python),
> plus de faux « external » ; docs alignées.
>
> 🔧 **Maintenance v1.0.4 (2026-08-20)** : catalogue enrichi — 5 agents
> **shell-ai** ajoutés (issues #94 #95) : AIChat (alias `ai`, binaire GitHub
> Release), ShellGPT (pip), Fabric (go), Shell AI (npm/Ollama), AI CLI
> (binaire, politique de sécurité risk/certainty). Catalogue : 77 agents.
>
> 🔧 **Maintenance v1.0.5 (2026-08-20)** : **commande `am ai` livrée**
> (issues #96 #97) — langage naturel → action shell via AIChat : mode
> conversationnel (aichat -f <ctx>), mode --exec avec pipeline de sécurité
> (génération aichat --dry-run, classification safe/risky + certainité,
> politique dry-run par défaut configurable settings.shell_ai, confirmation
> y/N pour les commandes risky, exécution via le shell de l'utilisateur),
> flags --files/--provider/--model/--yes, alias CLI `am shell`, événements
> `shell_ai` journalisés. Épique Axe 13 (#93) clôturée.
>
> 🔧 **Maintenance v1.0.6 (2026-08-20)** : installateur Windows corrigé —
> `install.ps1` n'acceptait que l'entrée `am.exe` dans l'archive de release
> (la CI et les archives manuelles utilisent `am-windows-x86_64.exe`) →
> repli systématique sur `cargo install` au lieu du binaire précompilé.
> Le script accepte désormais les deux noms ; archives v1.0.6 publiées avec
> les deux entrées pour la compatibilité maximale. Chemin du message
> cargo install corrigé (`.cargo\bin\am.exe`).
>
> 🚀 **Épique v1.1.0 (2026-08-20)** : **Onboarding, Copilot & Rôles aichat**
> (Axe 14) — `am setup` (wizard provider + token keyring + modèle + ping),
> installation automatique d'aichat (wizard + `am ai` + installateurs),
> 6 rôles copilot générés pour aichat (am-copilot, am-operator, am-dev,
> am-do, am-analyst, am-orchestrator), `am ai --role <nom>`, tip
> d'onboarding dans le banner REPL et les commandes IA (non-bloquant).
>
> 🔧 **Maintenance v1.1.1 (2026-08-20)** : fix `am setup` — le wizard écrivait
> `providers.<nom>` au TOP-LEVEL de la config user (clé rejetée par le
> validateur : « unknown field `providers` »). Le registre vivant sous
> `settings.providers`, le wizard écrit désormais
> `settings.providers.<nom>.base_url` + `.default_model` (le schéma exige
> base_url quand un bloc provider est écrit). Test de régression
> `setup_persists_under_settings_providers`.
>
> 🔧 **Maintenance v1.1.2 (2026-08-20)** :
> - `am setup` : **openrouter** ajouté au choix des providers (base URL,
>   token via OPENROUTER_API_KEY, 6 modèles déclarés proposés) ;
>   le choix du modèle liste les modèles disponibles du provider.
> - `am ai` sans `--role` utilise **am-copilot par défaut** (régénération
>   automatique des rôles si le fichier manque, dégradation douce).
> - Bug `am migrate --import` : la config importée était écrite dans le
>   répertoire config GLOBAL (user_config_dir) au lieu du config actif de
>   l'app — l'import écrasait la config réelle de la machine (et la suite
>   de tests détruisait la config utilisateur à chaque `cargo test`).
>   L'import respecte désormais `app.paths.config_dir` (--config/isolated).

---

## 📖 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 : 77 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 77 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/
        <session>.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 v3 | installations + résumé + annotations (★, notes, tags) | 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…) ✅ #49 | M | P2 |
| am monitor — TUI temps réel : CPU/mémoire par PID, uptime, alertes ✅ #50 | 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/<session>.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 ✅ #51 | 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 <id> — relance avec les mêmes args/env/cwd | M | P1 |
| am sessions export <id> + 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 ✅ #55 | L | P2 |
| Planification : am schedule add update --all --at 06:30 + check santé (cron / Task Scheduler) ✅ #56 | M | P2 |
| Orchestration de groupes : ordre, --parallel, attente de santé ✅ #57 | L | P2 |
| Conteneurs : profil docker/podman par agent (isolation à la demande) ✅ #58 | L | P2 |
| am doctor --watch — vérifications périodiques avec alertes ✅ #59 | 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 <url> | 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 ✅ #66 | L | P2 |
| Partage de catalogue d'équipe : include par URL | S | P2 |
| am migrate — assistant de transfert machine A → B ✅ #68 | 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 |

---

### Axe 13 — ⚡ Shell AI & Action ⭐

🎯 Transformer une commande en langage naturel en une action shell exécutée par un agent léger, rapide et contextuel, sans démarrer un gros coding agent.

**Contexte :** `am` gère aujourd'hui ~77 agents IA, principalement des *coding agents*, des assistants et des outils SaaS. Les shell assistants sont maintenant au catalogue (AIChat, ShellGPT, Fabric, Shell AI, AI CLI — v1.0.4) : légers, rapides, conçus pour transformer une phrase en commande ou action sur le système de fichiers local (ex. *"traite les fichiers JSON du dossier courant pour extraire les clés uniques"*).

---

#### 13.1 Agents shell AI découverts (✅ tous ajoutés au catalogue — v1.0.4, issues #94 #95)

| Outil | Repo | Langage | Force | Maturité |
|---|---|---|---|---|
| ✅ **AIChat** | `sigoden/aichat` | Rust | Shell assistant natif, RAG, agents, fichiers/répertoires, 20+ providers | **10.4k stars**, très actif |
| ✅ **ShellGPT** | `TheR1D/shell_gpt` | Python | Génère/exécute commandes shell, code, docs | Très connu, mature |
| ✅ **Fabric** | `danielmiessler/fabric` | Go | Patterns AI (summarize, extract wisdom), CLI | Très populaire, orienté contenu/texte |
| ✅ **Shell AI** | `nishant9083/shell-ai` | TypeScript | Agent ReAct local via Ollama, MCP, filesystem tools | Plus récent, prometteur mais jeune |
| ✅ **AI CLI** | `kriserickson/ai-cli` | Go | Natural language → commandes shell avec safety policy (`risk` / `certainty`) | Petit, simple, moins connu |

---

#### 13.2 Recommandation : AIChat (`sigoden/aichat`)

**Choix privilégié pour la fonction Shell AI.**

| Avantage | Détails |
|---|---|
| **Léger & rapide** | Rust, binaire unique, cold start rapide, idéal pour RPi 4 |
| **Shell Assistant natif** | Génère et exécute des commandes shell à partir du langage naturel |
| **Multi-provider** | OpenAI, Claude, Gemini, DeepSeek, Groq, Ollama, OpenRouter… |
| **Passage de contexte** | `aichat -f .` injecte le dossier ou les fichiers dans le prompt |
| **Mode exécution** | `aichat -e "..."` exécute directement, mode conversationnel sinon |
| **Facilité d'intégration** | Release binaire GitHub, installable via `binary` dans le catalogue |

Exemples d'usage ciblés :

```bash
# Lister et traiter les fichiers JSON du dossier courant
aichat -f . -e "liste tous les fichiers JSON et extrait les clés uniques"

# Résumer un dossier de fichiers
aichat -f . "résume les données de ces fichiers JSON"
```

---

#### 13.3 Fonctionnalités prévues

| Fonctionnalité | Description | Effort | Phase |
|---|---|---|---|
| ✅ **Catalogue : ajouter AIChat** | Définition `AgentDef` + alias `ai` → `aichat` — livré en v1.0.4 (issues #94 #95) | S | P1 |
| ✅ **Commande `am ai <prompt>`** | Lancer AIChat avec le dossier courant comme contexte — livré en v1.0.5 (issue #96) | S | P3 |
| ✅ **Flag `--exec` / `-e`** | Active le mode exécution directe (`aichat -e` via aichat --dry-run + exécution sécurisée par am) — livré en v1.0.5 (issue #96) | S | P3 |
| ✅ **Flag `--files <path>`** | Passer fichiers/dossiers spécifiques en contexte — livré en v1.0.5 (issue #96) | S | P3 |
| ✅ **Sécurité : `--dry-run` par défaut** | Simuler avant exécution ; classification safe/risky + confirmation — livré en v1.0.5 (issue #97, settings.shell_ai) | M | P3 |
| ✅ **Provider configurable** | Réutiliser le registre `providers.rs` (--provider/--model → env aichat + modèle) — livré en v1.0.5 (issue #96) | M | P3 |
| ✅ **Alias intégrés** | `am shell` comme synonyme CLI de `am ai` — livré en v1.0.5 (issue #96) | S | P3 |
| **Extensions sœurs** | `am summarize`, `am explain`, `am fix` (voir ci-dessous) | M | P3 |

---

#### 13.4 Risques & garde-fous

| Risque | Mitigation |
|---|---|
| Exécution automatique de commandes dangereuses | `--dry-run` par défaut, confirmation obligatoire avant toute commande `risky` |
| Coût API récurrent | Modèle cheap par défaut (`gpt-4.1-mini`, `gemini-flash`) ou Ollama local |
| Fuite de données sensibles | Support du mode local Ollama, pas d'envoi hors du provider configuré |
| Installation lente sur RPi | Utiliser l'installateur `binary` GitHub Releases plutôt que `cargo` |

---

#### 13.5 Idées sœurs (à intégrer ou lier à d'autres axes)

| Commande | Description | Axe lié |
|---|---|---|
| `am summarize <fichier/dossier>` | Résume un fichier ou un dossier via AIChat/Fabric | Axe 13 |
| `am explain <commande>` | Explique une commande shell avant exécution | Axe 13 |
| `am commit` | Génère un message de commit depuis `git diff` | Axe 13 / Axe 3 |
| `am review` | Review rapide d'un diff ou d'une PR | Axe 7 |
| `am translate <fichier> --to en` | Traduit un fichier markdown/doc | Axe 13 |
| `am ask-code "..."` | Pose une question sur le codebase sans lancer un gros agent | Axe 7 |
| `am doc <dossier>` | Génère un README/doc à partir du code | Axe 13 / Axe 7 |
| `am fix` | Corrige une commande shell qui a échoué | Axe 13 |
| `am note` | Extrait des action items d'un texte/réunion | Axe 10 |
| `am search-web "..."` | Recherche web rapide et réponse synthétisée | Axe 7 |

---

## 14. 🚀 Onboarding & Copilot aichat (épique v1.1.0)

> Objectif : réduire le **Time-To-First-Value à 0** — rendre `am` opérationnel
> pour l'IA locale dès la première seconde, et faire d'aichat le copilot de
> agent-manager. Livré en **v1.1.0 (2026-08-20)**.

| Fonctionnalité | Description | Statut |
|---|---|---|
| ✅ **Wizard d'onboarding (`am setup`)** | Provider (anthropic, openai, deepseek, google, ollama, custom), token masqué → trousseau OS (keyring, jamais en clair), modèle par défaut, ping API non-bloquant. Déclenché par `am ai`/`am ask`/banner REPL quand aucun provider n'est configuré (message discret, jamais bloquant), ré-exécutable à la main (mode revoir) | ✅ v1.1.0 |
| ✅ **Installation automatique d'aichat** | Étape du wizard « Installer le moteur IA (aichat) ? [Y/n] » → `am install aichat` (catalogue) ; `am ai` sans aichat propose l'installation ; install.ps1/install.sh enchaînent sur `am setup` si stdin interactif | ✅ v1.1.0 |
| ✅ **Rôles copilot aichat (am-*)** | 6 agents générés dans `~/.config/aichat/agents/` (ou %APPDATA%\\aichat\\agents) : am-copilot (guide & catalogue), am-operator (shell sécurisé), am-dev (code & git), am-do (exécution pure pour --exec), am-analyst (coûts/logs/stats), am-orchestrator (groupes/lab). Prompts bilingues (FR par défaut), privilégient les contrats `--json` | ✅ v1.1.0 |
| ✅ **`am ai --role <nom>`** | Rôle copilot passé à aichat (`--agent`) ; validation du fichier généré ; complétion REPL des rôles am-* ; config aichat créée (provider + modèle) seulement si absente | ✅ v1.1.0 |
| ✅ **Settings dédiés** | `settings.shell_ai` (default_safety dry-run/confirm/auto, risky_patterns) documenté dans config.yaml ; module `src/setup.rs` + `src/roles.rs` | ✅ v1.1.0 |

---

## 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

*Le suivi est en place sur Gitea : 4 milestones (v0.3.0 → v1.0), 22 labels
(P0–P3, axe-1…axe-12, S/M/L/XL, quick-win, epic) et les issues ci-dessous.
Chaque PR doit référencer son issue avec `closes #N` pour une clôture
automatique. Ordre de construction proposé pour la phase 0 — chaque étape
est un PR indépendant et testé :*

1. **[PR 1](https://git.dracodev.net/Projets/agent-manager/issues/2)** — src/events.rs : journal JSONL + rotation + tests.
2. **[PR 2](https://git.dracodev.net/Projets/agent-manager/issues/3)** — instrumentation start/stop/run (process.rs, run_cmd.rs) — dépend de PR 1.
3. **[PR 3](https://git.dracodev.net/Projets/agent-manager/issues/4)** — state.json v2 + migration additive — dépend de PR 1.
4. **[PR 4](https://git.dracodev.net/Projets/agent-manager/issues/5)** — sessions.json + am sessions + réconciliation — dépend de PR 2.
5. **[PR 5](https://git.dracodev.net/Projets/agent-manager/issues/6)** — am stats + am log (lecture du journal) — dépend de PR 2.
6. **[PR 6](https://git.dracodev.net/Projets/agent-manager/issues/7)** — historique structuré + am history (migration de history.txt).
7. **[PR 7](https://git.dracodev.net/Projets/agent-manager/issues/8)** — am init + détection de contexte (git, stack, cache) — dépend de PR 1.
8. **En parallèle** — les quick wins de la section 3 :
   [am logs #9](https://git.dracodev.net/Projets/agent-manager/issues/9) ·
   [am list --sort #10](https://git.dracodev.net/Projets/agent-manager/issues/10) ·
   [am config set #11](https://git.dracodev.net/Projets/agent-manager/issues/11) ·
   [am alias add #12](https://git.dracodev.net/Projets/agent-manager/issues/12) ·
   [dedup history.txt #13](https://git.dracodev.net/Projets/agent-manager/issues/13) ·
   [am doctor --json #14](https://git.dracodev.net/Projets/agent-manager/issues/14) ·
   [am version --json #15](https://git.dracodev.net/Projets/agent-manager/issues/15) ·
   [am open #16](https://git.dracodev.net/Projets/agent-manager/issues/16).

Épique de suivi : [issue #1](https://git.dracodev.net/Projets/agent-manager/issues/1) (Phase 0).

### Phase 1 — Cockpit (v0.4.0) — découpage créé le 2026-08-17

Épique : [issue #25](https://git.dracodev.net/Projets/agent-manager/issues/25) · milestone v0.4.0 · 17 issues.

| # | Issue | Effort |
|---|---|---|
| [#26](https://git.dracodev.net/Projets/agent-manager/issues/26) | Recherche fuzzy dans am search | M |
| [#27](https://git.dracodev.net/Projets/agent-manager/issues/27) | Ctrl-R + réexécution dans le REPL | M |
| [#28](https://git.dracodev.net/Projets/agent-manager/issues/28) | am history --rerun N | S |
| [#29](https://git.dracodev.net/Projets/agent-manager/issues/29) | am projects + profils de projet | M |
| [#30](https://git.dracodev.net/Projets/agent-manager/issues/30) | am start contextuel (dépend de #29) | S |
| [#31](https://git.dracodev.net/Projets/agent-manager/issues/31) | am timeline (vue chronologique unifiée) | M |
| [#32](https://git.dracodev.net/Projets/agent-manager/issues/32) | am sessions resume <id> | M |
| [#33](https://git.dracodev.net/Projets/agent-manager/issues/33) | am dashboard (TUI temps réel) | L |
| [#34](https://git.dracodev.net/Projets/agent-manager/issues/34) | Hooks on_install/on_start/on_stop/on_update | M |
| [#35](https://git.dracodev.net/Projets/agent-manager/issues/35) | am watch --restart-on-crash --notify | M |
| [#36](https://git.dracodev.net/Projets/agent-manager/issues/36) | am secret (keyring OS) + injection --env | M |
| [#37](https://git.dracodev.net/Projets/agent-manager/issues/37) | am top + am report (rapport hebdo/mensuel) | M |
| [#38](https://git.dracodev.net/Projets/agent-manager/issues/38) | am log --follow (flux en direct) | S |
| [#39](https://git.dracodev.net/Projets/agent-manager/issues/39) | Favoris, notes et tags personnels | M |
| [#40](https://git.dracodev.net/Projets/agent-manager/issues/40) | Profils d'environnement (am profile dev/prod) | M |
| [#41](https://git.dracodev.net/Projets/agent-manager/issues/41) | Complétions dynamiques + man pages | S |
| [#42](https://git.dracodev.net/Projets/agent-manager/issues/42) | Packaging officiel (winget/scoop/deb/Homebrew) + CI | M |

Critère de sortie du jalon : retrouver n'importe quelle action passée en
moins de 2 secondes.

### Phase 2 — Automatisation (v0.5.0) — découpage créé le 2026-08-17

Épique : [issue #47](https://git.dracodev.net/Projets/agent-manager/issues/47) · milestone v0.5.0 · 27 issues.

| # | Issue | Effort |
|---|---|---|
| [#49](https://git.dracodev.net/Projets/agent-manager/issues/49) | Suivi des coûts — tokens/€ par session (stats --costs, cost_models) ✅ | M |
| [#50](https://git.dracodev.net/Projets/agent-manager/issues/50) | am monitor — TUI temps réel (CPU/mémoire par PID, alertes) ✅ | L |
| [#51](https://git.dracodev.net/Projets/agent-manager/issues/51) | ✅ Playbooks — am history --save + am playbook | L |
| [#52](https://git.dracodev.net/Projets/agent-manager/issues/52) | ✅ Templates — am init --template web/python/rust/cli (substitution + validation) | M |
| [#53](https://git.dracodev.net/Projets/agent-manager/issues/53) | ✅ am sessions export + rétention configurable (sessions_retention_days) | M |
| [#54](https://git.dracodev.net/Projets/agent-manager/issues/54) | ✅ am web — serveur local + API JSON + graphiques (dashboard embarqué, contrats --json, 127.0.0.1) | XL |
| [#55](https://git.dracodev.net/Projets/agent-manager/issues/55) | Services système — am service install (systemd/launchd/tâches Windows) ✅ | L |
| [#56](https://git.dracodev.net/Projets/agent-manager/issues/56) | Planification — am schedule (add --at / list / remove / run) ✅ | M |
| [#57](https://git.dracodev.net/Projets/agent-manager/issues/57) | Orchestration de groupes (ordre, --parallel, attente de santé) ✅ | L |
| [#58](https://git.dracodev.net/Projets/agent-manager/issues/58) | Conteneurs — profils docker/podman par agent ✅ | L |
| [#59](https://git.dracodev.net/Projets/agent-manager/issues/59) | am doctor --watch — vérifications périodiques avec alertes ✅ | M |
| [#60](https://git.dracodev.net/Projets/agent-manager/issues/60) | ✅ Catalogue distant — am catalog update / am catalog add <url> | M |
| [#61](https://git.dracodev.net/Projets/agent-manager/issues/61) | ✅ am suggest — « un agent pour du Python » (tags + usage réel) | M |
| [#62](https://git.dracodev.net/Projets/agent-manager/issues/62) | ✅ am lab — benchmark : même tâche sur N agents | L |
| [#63](https://git.dracodev.net/Projets/agent-manager/issues/63) | ✅ am audit — qui a modifié quoi quand | M |
| [#64](https://git.dracodev.net/Projets/agent-manager/issues/64) | ✅ am update --rollback — backup automatique avant mise à jour | M |
| [#65](https://git.dracodev.net/Projets/agent-manager/issues/65) | ✅ Politiques — pin de version, settings.update_policy | S |
| [#66](https://git.dracodev.net/Projets/agent-manager/issues/66) | ✅ Synchronisation git automatique — am sync (sync_repo, sync_on_exit, secrets exclus) | L |
| [#67](https://git.dracodev.net/Projets/agent-manager/issues/67) | ✅ Partage de catalogue d'équipe (include par URL) | S |
| [#68](https://git.dracodev.net/Projets/agent-manager/issues/68) | ✅ am migrate — assistant de transfert machine A → B (bundle .amx + doctor) | M |
| [#69](https://git.dracodev.net/Projets/agent-manager/issues/69) | ✅ Thèmes couleurs du REPL | S |
| [#70](https://git.dracodev.net/Projets/agent-manager/issues/70) | ✅ am models — inventaire des modèles locaux (ollama, llama.cpp, LM Studio) | M |
| [#71](https://git.dracodev.net/Projets/agent-manager/issues/71) | ✅ Lien agent ↔ modèle — am run --model | M |
| [#72](https://git.dracodev.net/Projets/agent-manager/issues/72) | ✅ doctor vérifie ollama / llama-server comme n'importe quel outil | S |
| [#73](https://git.dracodev.net/Projets/agent-manager/issues/73) | ✅ am models prune — purge des modèles inutilisés | S |
| [#74](https://git.dracodev.net/Projets/agent-manager/issues/74) | ✅ i18n — messages EN/FR (--lang, AM_LANG/LANG, catalogue tr/tr_fmt) | L |
| [#75](https://git.dracodev.net/Projets/agent-manager/issues/75) | ✅ Plugin scripts (hooks avancés, intégration CI) | M |

Critère de sortie du jalon : parc auto-supervisé (crash = redémarrage +
alerte).

### Phase 3 — Plateforme (v1.0) — découpage créé le 2026-08-17

Épique : [issue #48](https://git.dracodev.net/Projets/agent-manager/issues/48) · milestone v1.0 · 5 issues.

| # | Issue | Effort |
|---|---|---|
| [#76](https://git.dracodev.net/Projets/agent-manager/issues/76) | ✅ Télémétrie anonyme opt-in (compteurs agrégés uniquement) | M |
| [#77](https://git.dracodev.net/Projets/agent-manager/issues/77) | ✅ Registre communautaire — am registry (publication + recherche sur Gitea) | L |
| [#78](https://git.dracodev.net/Projets/agent-manager/issues/78) | ✅ am ask — langage naturel → commande am (fournisseur LLM optionnel) | L |
| [#79](https://git.dracodev.net/Projets/agent-manager/issues/79) | ✅ Profils sandbox par agent (commandes/répertoires autorisés) | L |
| [#80](https://git.dracodev.net/Projets/agent-manager/issues/80) | ✅ am serve --token — API HTTP + WebSocket pour piloter à distance | XL |

Critère de sortie du jalon : dashboard web complet + API distante.

### Phase v0.7.0 — Providers & configuration automatisée (P0, PRIORITAIRE)

Épique : [issue #87](https://git.dracodev.net/Projets/agent-manager/issues/87)
· milestone v0.7.0 · 5 issues · **priorité P0 : livrée AVANT la Phase 3
(v1.0, #76–#80 en P3), sauf dépendances**.

Centralise tokens/providers/modèles dans UN registre (settings.providers +
keyring partagé) et configure automatiquement les agents à l'installation :
`am install <agent>` branche le provider/modèle par défaut,
`--provider/--model` pour surcharger, `--no-config` pour le comportement
actuel, `am run --provider` pour surcharger au lancement (cloud inclus).
S'appuie sur #36 (secrets), #40 (profils), #71 (modèle), #66 (sync) — livrés.

| # | Issue | Effort | Dépend de |
|---|---|---|---|
| [#88](https://git.dracodev.net/Projets/agent-manager/issues/88) | ✅ Registre de providers + commandes `am providers` (settings.providers, default_provider) | M | — |
| [#89](https://git.dracodev.net/Projets/agent-manager/issues/89) | ✅ Secrets partagés par provider (namespace keyring + résolution `@secret` fallback) | S | #88 |
| [#90](https://git.dracodev.net/Projets/agent-manager/issues/90) | ✅ AgentDef provider/model + flags `--provider/--model/--no-config` à l'install | M | #88 |
| [#91](https://git.dracodev.net/Projets/agent-manager/issues/91) | ✅ Configuration post-install : bloc `config:` par agent (env_map + fichiers) | L | #89, #90 |
| [#92](https://git.dracodev.net/Projets/agent-manager/issues/92) | ✅ `am run/start --provider` : override au lancement (providers cloud inclus) | M | #90 |

Critère de sortie du jalon : un agent installé est opérationnel sans
configuration manuelle (tokens au keyring, provider/modèle par défaut).

---

*Document généré à partir de l'analyse du code (v0.2.7, commit d886de3).
Phases livrées : 0 (v0.3.0), 1 (v0.4.1), 2 (v0.6.0), v0.7.0 (providers,
2026-08-19), 3 (v1.0.0, #76–#80, 2026-08-20) ; maintenance v1.0.1/v1.0.2
(self-update décompression, REPL), v1.0.3 (détection externe), v1.0.4
(catalogue shell AI, #94 #95), v1.0.5 (commande am ai, #93 #96 #97),
v1.0.6 (installateur Windows accepte l'entrée am-windows-x86_64.exe).*