Table of Contents

🇬🇧 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"
  1. 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.
  2. 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 /inpdf en lecture et /outmd en écriture — ou, s'il n'en nomme aucun, /workspace à lire (seulement si quelque chose entre) et /output où é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 un forge resume — comme le fait un client qui confirme les dossiers dans un run --dry d'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 (un FORGE-FOLDERS-INVALID ré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.filled sur le canal d'événements ; --auto n'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.
  3. 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 rendu source: 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.
  4. 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é dans runs/<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 le folders/<nom> de la session, qui rejoint l'équipe à l'adoption — et /forge contient les fichiers de travail de la session ; shell_command/code_interpreter et les onze outils drive_* 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 le memory: 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ée deliverableMissing sur son task.completed, et le run.finished de l'essai la compte dans missingDeliverables. Une tâche dont l'agent a fini sur son plafond d'itérations porte endedOnIterationCap sur son task.completed, et run.finished la compte dans cappedTasks.
  5. 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 ✔.
  6. 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à. --auto arbitre 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/ ; /workspace lit input/) — 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 que forge reopen lit 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-fournisseur enregistre celui qu'utilise votre système, et note ce qu'il a enregistrĂ© dans schedule/installed.json (--check dit oĂą il en est, orkeon forge unschedule le 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.