Key Concepts.fr

Concepts clés

Cette page définit le vocabulaire fondamental de WorkPilot AI. Si vous ne lisez qu'une page, c'est celle-ci.

---

🤖 Agent

Un agent est un programme piloté par un modèle d'IA (Claude, GPT-4, Gemini…) qui exécute une tâche précise : planifier, coder, tester, corriger, documenter, etc.

Chaque agent a :

• un prompt système (apps/backend/prompts/<agent>.md) qui définit son rôle
• un modèle assigné (configurable par phase)
• un budget de réflexion (max_thinking_tokens)
• des outils autorisés (lecture fichier, bash, etc.)
• une session isolée via ClaudeSDKClient

WorkPilot AI utilise exclusivement le Claude Agent SDK pour uniformiser la couche agent. Cela permet la journalisation, les hooks de sécurité et la gestion d'erreurs au même endroit.

---

📝 Spec (spécification)

Une spec est un dossier auto-contenu qui décrit tout ce qui est à faire pour une tâche donnée.

.workpilot/specs/001-nom-fonctionnalite/
├── spec.md                   # description humainement lisible
├── requirements.json          # critères d'acceptation structurés
├── context.json               # fichiers pertinents, dépendances
├── implementation_plan.json   # découpage en phases
├── qa_report.md               # résultats de la revue QA
└── QA_FIX_REQUEST.md          # demandes de correction en cours

La spec est le contrat entre l'utilisateur, les agents et le système de validation. C'est également l'unité de persistance : vous pouvez reprendre une spec interrompue avec --continue.

---

🎯 Critères d'acceptation

Les critères d'acceptation sont des conditions vérifiables inscrites dans la spec. Exemples :

• « L'endpoint /health répond 200 OK »
• « Tous les tests existants passent »
• « Un nouveau test d'intégration couvre le cas d'erreur 500 »

Le QA Reviewer vérifie un à un ces critères. Tant qu'un critère échoue, le QA Fixer continue à corriger (jusqu'à 50 itérations max).

---

🌳 Worktree (arbre de travail Git)

Un git worktree est une copie isolée du dépôt sur une autre branche. WorkPilot AI crée un worktree dédié pour chaque tâche :

mon-projet/
├── .git/
├── src/                      # ← votre main
└── .worktrees/
    └── workpilot-ai/         # ← worktree isolé où les agents codent
        └── src/

Pourquoi c'est important :

• Votre branche principale ne peut pas être cassée par une tâche en cours
• Plusieurs tâches peuvent s'exécuter en parallèle sans s'interférer
• Vous pouvez tester le worktree comme un projet normal (npm run dev dedans)
• Si le résultat ne convient pas, un simple --discard supprime le worktree

---

🧪 Pipeline QA (validation)

Après que le Coder a terminé, une boucle de validation démarre automatiquement :

QA Reviewer  →  Critères OK ? →  [oui] Prêt à fusionner
     ↓                [non]
QA Fixer  →  Corrige et relance
     ↓
(loop jusqu'à succès ou 50 itérations)

Le QA Reviewer lit les critères d'acceptation et vérifie chaque point. S'il détecte des échecs, il génère un QA_FIX_REQUEST.md que le QA Fixer lit et applique.

👉 Plus de détails : Pipeline multi-agents

---

🔀 Fusion sémantique (Semantic Merge)

Quand plusieurs worktrees doivent revenir sur main, les conflits git classiques peuvent survenir. WorkPilot AI utilise un moteur de fusion sémantique IA qui comprend l'intention de chaque changement et les combine intelligemment.

Exemple : si deux tâches modifient le même fichier config.ts mais pour ajouter deux nouvelles clés différentes, la fusion sémantique conserve les deux — là où un merge git classique lèverait un conflit.

---

🎛 Mission Control

Tableau de bord multi-agents inspiré des salles de contrôle NASA. Il affiche en temps réel :

• Tous les agents en cours d'exécution
• Leur statut (planning, coding, reviewing…)
• Consommation de tokens par agent
• Fichiers modifiés
• Raisonnement en direct (chain-of-thought)
• Budget global et alertes de coût

Particulièrement utile quand plusieurs tâches tournent en parallèle.

---

🧠 Mémoire (Graphiti)

Graphiti est un système de mémoire graphe sémantique qui permet aux agents de retenir des connaissances entre sessions. Au lieu de redécouvrir votre projet à chaque tâche, les agents peuvent requêter :

• « Qu'ai-je appris sur l'authentification dans ce projet ? »
• « Quels fichiers sont liés à la feature X ? »
• « Quel style de code l'équipe préfère ? »

Les nœuds du graphe = entités (fichiers, classes, concepts), les arêtes = relations (importe, appelle, dépend de, etc.).

👉 Plus de détails : Système de mémoire

---

⚡ Skills (compétences dynamiques)

Les Skills sont des capacités d'agents réutilisables et optimisées : migration de framework, refactoring, génération de tests, etc.

Caractéristiques :

• Optimisation des tokens (compression de métadonnées, descriptions ≤ 512 chars)
• Gestion de contexte (compactage agressif à 70 % du budget, checkpoints)
• Délégation à des sous-agents (par défaut max_workers=3, timeout 25 s)
• Enregistrement dynamique (validation runtime)

Un skill s'invoque via le skill_manager :

result = await skill_manager.execute_skill(
    skill_name="framework-migration",
    action="analyze",
    context={"framework": "react", "project_path": "/path/to/project"}
)

---

🔗 MCP (Model Context Protocol)

MCP est un standard ouvert pour connecter des LLMs à des outils externes (bases de données, APIs, filesystem, navigateurs…). WorkPilot AI inclut :

• Une MCP Marketplace pour parcourir et installer des serveurs MCP
• Le support des MCPs personnalisés avec authentification locale
• Des intégrations prêtes : Chrome DevTools MCP, Electron MCP, grepai…

👉 Plus de détails : Intégrations

---

👤 Profil Claude

Un profil Claude est un jeu de credentials (OAuth ou clé API) pour un compte d'IA. WorkPilot AI permet d'enregistrer plusieurs profils et bascule automatiquement entre eux :

• Rate limit atteint sur le compte A → bascule auto vers le compte B
• Scoring par disponibilité et usage récent (profile-scorer.ts)
• Stockage sécurisé dans le trousseau OS (Keychain / Credential Manager)
• Rafraîchissement automatique des tokens OAuth

---

🔒 Sandbox et allowlist

Chaque exécution d'agent est encadrée par trois couches de sécurité :

1. Sandbox OS — les commandes bash s'exécutent en isolation
2. Restrictions filesystem — opérations limitées au répertoire projet
3. Allowlist dynamique — commandes approuvées selon la stack détectée (pas de rm -rf /, pas d'accès réseau inattendu…)

👉 Plus de détails : Sécurité

---

📊 Workflow Logger

Journalisation structurée de toutes les exécutions (agents, skills, hooks) avec :

• 🤖 Logs d'agents
• ⚡ Logs de skills
• 🪝 Logs de hooks
• Trace IDs pour corréler les événements
• Durées automatiques
• Sortie humaine lisible + JSON

Fichier : logs/workflow.log.

---

🧭 Tier de complexité

Chaque tâche est classée automatiquement par l'agent d'évaluation en trois niveaux :

Tier	Phases	Déclencheur
SIMPLE	3	1-2 fichiers, aucune intégration
STANDARD	6	3-10 fichiers, 1-2 services
COMPLEX	8	10+ fichiers, multi-services, intégrations externes

Le nombre de phases influence la profondeur de planification et la robustesse des checks QA.

---

Prochaine étape

➡️ Visite guidée de l'interface utilisateur