🇬🇧 English version
Forger une équipe à partir d'un besoin
Vous ne voulez pas construire une équipe d'agents — vous voulez résoudre un problème concret. L'Atelier (orkeon forge) est le parcours guidé entre les deux : vous décrivez le problème en langage naturel, un assistant en fait une équipe, l'équipe est essayée en bac à sable sur votre propre exemple, et le résultat est jugé contre les critères d'acceptation que vous avez énoncés — pas contre un vague « c'est bien ? ».
Brief ──▶ Blueprint ──▶ Render ──▶ Validate ──▶ Test ──▶ Diagnose ──▶ Verdict
▲ │ │ │
└───── correction ◀──────┴── (erreurs de validation) ──────┤ (non conforme)
│ ▼
└─────────────▶ Ready ──▶ Promote
(adopter sans essayer)
Prérequis
Un LLM configuré. Si ce n'est pas encore fait :
orkeon init # l'assistant à 5 choix (ollama, openai, custom…)
orkeon doctor # vérifier l'installation
La forge refuse d'ouvrir l'entretien sans modèle (FORGE-LLM-UNAVAILABLE) — elle ne ferait que vous renvoyer vos mots en écho.
Le cycle, de bout en bout
orkeon forge "résumer chaque matin les nouvelles offres de mon fournisseur"
- L'entretien. L'assistant ne demande que ce que votre besoin laisse dans l'ombre — ce qui entre, ce qui sort et sous quelle forme —, une question courte à la fois, et jamais à quelle fréquence le travail tourne (la planification se règle à la promotion). Un besoin qui dit déjà tout passe sans aucune question ; « je ne sais pas » est toujours une réponse valide. Il capte un brief structuré : objectif, entrées, sortie attendue, contraintes, critères d'acceptation (ce que « fait, et bien fait » veut dire, dans vos mots), et un exemple d'entrée pour l'essai.
- Les dossiers. Entre le brief et le plan, la forge propose les dossiers de l'équipe : ceux que votre besoin nomme — « …des PDF dans
/inpdf, le Markdown dans/outmd» donne/inpdfen lecture et/outmden écriture — ou, s'il n'en nomme aucun,/workspaceà lire (seulement si quelque chose entre) et/outputoù écrire. Le terminal accepte la proposition telle quelle et l'affiche ; un client qui pilote la forge peut en faire une étape où vous renommez un dossier, le reliez à un dossier réel ou le gardez dans l'équipe, puis confirmez. Dès lors, cette liste est celle des dossiers de l'équipe : le plan y livre, l'essai les monte, l'équipe promue les porte. Un dossier relié à un dossier réel hors de votre répertoire de travail est lu par un essai que lance unforge resume— comme le fait un client qui confirme les dossiers dans un run--dryd'abord : le processus qui essaie une équipe ne peut lire que les dossiers avec lesquels il a démarré, si bien qu'un run sur le point d'essayer l'équipe dans le même processus refuse ce dossier à la confirmation (unFORGE-FOLDERS-INVALIDrécupérable) et dit comment faire. Quand un dossier est gardé dans l'équipe, la forge attend ensuite que vous y déposiez ses fichiers — Entrée dans le terminal,folders.filledsur le canal d'événements ;--auton'attend pas — et verse ce que chacun contient dans le brief, si bien que le plan est fait pour ces fichiers. Quand le dossier est une boîte de dépôt dont le contenu change d'un run à l'autre, dites-le dans votre besoin (« les documents déposés dans/documents, quels qu'ils soient ») : l'assistant marque le dossier (examples), les fichiers que vous déposez sont alors des exemples de ce qui viendra, et le plan n'en nomme aucun. - La proposition. Du brief, l'assistant planifie une équipe : qui fait quoi, dans quel ordre, avec quels outils — tirés du seul catalogue réel ; il ne peut pas en inventer. Le plan est rendu en fichiers de crew ordinaires et validé mécaniquement (outils inconnus, tâches sans agent, cycles de dépendances, et une tâche ou un agent qui nomme un fichier sous un dossier de livrables sans dépendre de la tâche qui l'écrit — un fichier déjà présent sous un dossier de sortie compte comme écrit ; voir
orkeon forge). Les erreurs de validation repartent chez l'assistant pour réparation — deux fois, puis elles remontent vers vous. Un livrable texte que l'un des agents capables d'exécuter sa tâche ne peut pas écrire (aucun outil d'écriture, ni le sien ni accordé par la tâche) est rendusource: final_message(le framework y enregistre la réponse finale de l'agent) ; un livrable binaire (.docx,.xlsx…) demande l'outil qui écrit son format, sinon le plan échoue à la validation. - L'essai. L'équipe tourne dans un bac à sable, in-process, sur votre exemple d'entrée, avec les dossiers confirmés montés et rien d'autre des vôtres : chaque dossier de sortie atterrit dans le dossier de la session (
folders/<nom>, mis de côté dansruns/<n>/folders/<nom>après chaque essai), un dossier d'entrée lit le dossier réel que vous lui avez relié — sinon--read, sinon l'espace de travail pour/workspace, sinon lefolders/<nom>de la session, qui rejoint l'équipe à l'adoption — et/forgecontient les fichiers de travail de la session ;shell_command/code_interpreteret les onze outilsdrive_*sont retirés du catalogue, tout simplement (un essai n'a pas de drive à lire). Le confinement porte sur le dossier de session. Un essai tourne sans mémoire, quoi que dise lememory:du plan : il ne range rien et ne rappelle rien, si bien que l'équipe promue ne rappelle jamais la sortie d'un essai comme l'un de ses runs précédents — sa mémoire commence avec son premier vrai run. Une tâche qui se termine sans écrire le fichier qu'elle déclare est signaléedeliverableMissingsur sontask.completed, et lerun.finishedde l'essai la compte dansmissingDeliverables. Une tâche dont l'agent a fini sur son plafond d'itérations porteendedOnIterationCapsur sontask.completed, etrun.finishedla compte danscappedTasks. - Le verdict. Un juge note la sortie contre vos critères d'acceptation, un à un, et énonce des constats et des suggestions concrètes. Un critère must raté bloque quel que soit le score. Si aucun juge ne peut tourner, le verdict le dit (
judge: deterministic) — il n'invente jamais un ✔. - Votre arbitrage. Le mode interactif arbitre chaque verdict, conformes compris : accepter (une équipe conforme devient prête ; accepter une non conforme, c'est juger sur pièce), refaire l'essai tel quel (
retry— zéro jeton de composition, une itération de budget), corriger (le diagnostic est réinjecté dans le plan, mot pour mot), rendre un plan édité à la main (edit), ou en rester là .--autoarbitre seul, dans les limites du budget.
L'adoption elle-même n'est pas une porte à sens unique : forge resume d'une session promue la rouvre à l'arbitrage (le verdict stocké est ré-annoncé), et un second forge promote vers la même destination — ou vers ce dossier déplacé ou renommé depuis — met le dossier à jour en place — fichiers générés régénérés, vos propres fichiers préservés. Toute autre destination non vide reste refusée, copie du dossier comprise. Et la session n'est pas non plus un prérequis : forge reopen <dossier-equipe> retrouve la session à laquelle le dossier est lié par l'identifiant que porte son forge.json, ou en reconstruit une depuis le crew/ du dossier (et ce forge.json) quand l'originale a disparu — ou quand le dossier est une copie, qui reçoit alors une session à elle — en se posant à la pause --dry : une équipe importée, orpheline ou dupliquée peut être amendée, essayée et ré-adoptée sur le même dossier, pas seulement relancée.
Tout est borné : 3 itérations par défaut (--max-iterations), plafonds optionnels de jetons et de temps (--max-tokens, --max-seconds). Un budget épuisé arrête le cycle proprement ; une reprise peut le relever — la consommation est toujours reportée.
La session sur disque
Chaque cycle vit sous .orkeon/forge/<slug>/ dans votre répertoire de travail :
.orkeon/forge/veille-fournisseur/
├── session.json identifiant, état, statut, budget — le point de reprise
├── brief.json ce que vous avez demandé, critères compris
├── folders.json les dossiers confirmés, avec le dossier réel derrière chacun
├── folders/<nom>/ un dossier gardé dans l'équipe jusqu'à l'adoption ; les sorties de chaque essai
├── blueprint.json le plan d'équipe (source unique des deux rendus)
├── repair.json les erreurs de validation qu'une réparation doit corriger, tant qu'elle est en attente
├── crew/ la crew rendue — ce qui tourne vraiment
├── runs/<n>/ chaque essai : sortie, métriques, verdict, livrables (folders/<nom>/)
├── transcript.jsonl la conversation
└── history.jsonl chaque transition d'état
orkeon forge list # ce qui est en cours, ce qui est prĂŞt
orkeon forge resume veille-fournisseur # reprendre exactement là où c'était
orkeon forge "..." --dry # générer et valider seulement — jamais exécuter
orkeon forge resume veille-fournisseur --edit --dry # amender le plan Ă la pause, re-rendre, re-pauser
orkeon forge resume veille-fournisseur --adopt # garder l'équipe telle quelle, sans essai
À la pause --dry, vous pouvez amender le plan avant même de l'essayer : resume --edit lit le blueprint amendé sur le canal, le valide intégralement, re-rend de façon déterministe — zéro jeton LLM, même itération — et avec --dry se remet en pause à la même frontière.
La même pause accepte une seconde réponse : resume --adopt garde l'équipe telle qu'elle a été générée et passe directement à Ready — hors ligne, sans dossier d'exécution, zéro jeton. Ce qui est sauté, ce sont les preuves que produit un essai, jamais un contrôle : à cette pause le crew est rendu et validé, et la promotion n'a jamais consommé d'artefact d'essai — FORGE.md écrit simplement « aucun verdict enregistré ».
Deux formats, une seule génération
L'assistant n'écrit jamais ni YAML ni TypeScript — il produit un plan validé par schéma, et un renderer déterministe en dérive les fichiers. --format yaml (défaut) rend le layout YAML par entité ; --format script rend un crew.ork.ts éditable — l'équivalent scripté de la même crew, un point de départ pour vos propres retouches, pas de la logique conditionnelle. Le chemin script exige esbuild ; sans lui, une nouvelle session retombe sur YAML et le dit (FORGE-ESBUILD-MISSING).
Les deux rendus convergent vers le même validateur, et l'essai charge la crew depuis les fichiers rendus — ce qui est écrit est ce qui tourne.
L'adopter
orkeon forge promote veille-fournisseur --to ~/solutions/veille-fournisseur \
--name "Veille fournisseur" --schedule daily@07:30
--name est le nom de l'équipe : il devient le titre de la carte, du jumeau et de la session. Une fois le dossier écrit, la session suit l'équipe — son dossier sous .orkeon/forge/ prend le nom du dossier de destination (-2 si une autre session le porte déjà ), si bien que forge list la montre sous le nom de l'équipe qu'elle a produite.
Le dossier promu est ordinaire — rien n'y est propriétaire à la forge :
crew/— l'équipe, telle qu'essayée ;- un dossier par dossier confirmé (
inpdf/,outmd/;/workspacelitinput/) — créé à la promotion, avec ce que la session gardait pour lui, pour que le premier lancement ait où lire et écrire ; run.sh/run.cmd— des scripts de lancement qui se placent (cd) dans le dossier, portent les montages liant ces dossiers (--mount "$DIR/outmd":/outmd:rw) et ont vos entrées d'exemple pré-remplies (à adapter au vrai usage) ;FORGE.md— la carte d'identité de l'équipe : objectif, critères d'acceptation, verdict, date et version de génération — ce qu'un collègue lit en récupérant le dossier ;forge.json— le jumeau lisible par la machine de la carte : identifiant, slug, titre, format, instant de promotion de la session et le brief — l'identifiant relie le dossier à sa session où qu'aille le dossier, et le reste est ce queforge reopenlit pour reconstruire une session fidèle une fois l'originale disparue (rien de secret dedans) ;schedule/(avec--schedule) — un XML de tâche Windows, un timer systemd, une ligne cron, tous au nom du dossier d'équipe (orkeon-veille-fournisseur.timer). La promotion n'en installe aucun :orkeon forge schedule ~/solutions/veille-fournisseurenregistre celui qu'utilise votre système, et note ce qu'il a enregistré dansschedule/installed.json(--checkdit où il en est,orkeon forge unschedulele retire). Orkeon n'a pas d'ordonnanceur à lui — c'est le système qui lance l'équipe —, il ne promet donc aucune supervision qu'il ne peut pas donner.
Lancez-la par son propre script — ~/solutions/veille-fournisseur/run.sh. Un orkeon run ~/solutions/veille-fournisseur/crew nu la lance aussi : le config.yaml promu nomme les dossiers que l'équipe utilise (mounts: [/inpdf, /outmd]), si bien qu'une entrée des settings déclarant /outmd est utilisée telle quelle, et qu'à défaut le run est refusé en une ligne (the crew requires '/outmd' … pass --mount <folder>:/outmd:rw) au lieu d'écrire nulle part.
Autres options
| Option | S'applique Ă | Effet |
|---|---|---|
--read <dir> |
une nouvelle session, forge resume |
Le dossier que l'essai lit derrière le premier dossier d'entrée relié à aucun dossier réel (/workspace par défaut), à la place du répertoire de travail — pour pointer un essai sur les documents que l'équipe doit lire ; les sessions restent sous le répertoire de travail. |
--reference <id> |
une nouvelle session | Compose l'équipe à partir d'un cas d'usage du catalogue (orkeon usecases list) : la structure de sa crew sert de modèle à l'assistant, et la session, forge.json et FORGE.md l'enregistrent. |
--lang <code> |
une nouvelle session, forge resume |
La langue dans laquelle l'assistant converse et nomme l'équipe (fr, en, es, de, zh ; l'anglais par défaut) — jusqu'à ce que vous écriviez dans une autre langue ou le demandiez. |
--settings <path> |
une nouvelle session, forge resume |
Le fichier de settings, avec la même sémantique qu'orkeon run --settings. |
--with-settings |
forge promote |
Copie le fichier de settings résolu dans le dossier promu. Désactivé par défaut : un fichier de settings contient souvent des clés API et le dossier est fait pour être partagé — sans la copie, les scripts de lancement référencent le fichier sur place. |
--events jsonl |
chaque verbe | Le protocole d'événements versionné sur stdout, les réponses sur stdin — c'est ainsi qu'un client externe pilote la forge. |
--pack <dir> |
une nouvelle session, forge resume |
Un dossier dont les fichiers remplacent le pack embarqué de l'assistant. |
orkeon forge rename <dossier-equipe> --name "<nouveau nom>" renomme une équipe promue — chaque titre, le dossier lui-même, le dossier de la session liée et une planification installée — tout ou rien.
Limites honnĂŞtes
- La qualité de la proposition suit le modèle que vous avez configuré ; les critères du brief et la validation mécanique sont les garde-fous, pas un substitut.
- Le bac à sable restreint en retirant les outils du catalogue, pas en espérant que le modèle s'abstienne ; les outils réseau n'atteignent le plan que si votre brief les a demandés.
- Le mail est essayé, jamais envoyé : les douze outils de boîte aux lettres sont proposés, et chaque essai les joue sur une boîte d'essai fictive ; les envois, brouillons et modifications qu'il aurait faits sont montrés sous le verdict et rien n'atteint une vraie boîte (Crews forgés).
- Une session, un problème : l'Atelier génère et valide une équipe — ce n'est pas un éditeur visuel de crews.