Introduction

Dans mon cas, ce n’est ni un SDK ni une bibliothèque qu’il faudrait connecter au code produit. C’est plutôt une couche d’ingénierie portable pour travailler avec Copilot au niveau du dépôt. Son objectif est de rassembler au même endroit les bonnes pratiques : structure des instructions, templates, processus de bootstrap, catalogue de rôles agentiques, scoped instructions, skills, repo context et observabilité de base. Le besoin d’un tel framework est apparu après que j’ai reconstruit plusieurs fois de suite la même structure de travail. On recrée encore AGENTS.md, PROJECT.md, llms.txt et copilot-instructions.md. On redécoupe encore les rôles en planner, executor, critic et reviewer. On réfléchit encore à la manière de stocker le contexte sur plusieurs dépôts, de journaliser les étapes, de limiter l’accès aux outils et de savoir où arrêter les tentatives infinies de l’agent. Après plusieurs répétitions de ce type, il devient clair que ce n’est plus un ensemble de techniques isolées. C’est une couche d’ingénierie distincte, qu’il vaut mieux décrire, standardiser et réutiliser entre projets.

Qu’est-ce que ForgentFramework

ForgentFramework se comprend le mieux non pas comme une bibliothèque ni comme un runtime intégré dans une application, mais comme une couche séparée au niveau du dépôt, qui aide à organiser le travail avec Copilot et les agents de la même manière dans différents projets. En termes simples, ce n’est pas « encore un prompt intelligent ». C’est un ensemble de fichiers, de règles, de rôles, de templates et de processus que l’on peut transférer dans un nouveau projet pour ne pas reconstruire tout le schéma agentique à partir de zéro. Un tel framework contient :

• spécification ;
• templates ;
• outils de bootstrap ;
• catalogue d’agents ;
• project instructions ;
• scoped instructions ;
• prompts ;
• skills ;
• repo context ;
• fichiers de session ;
• artefacts de trace.

L’idée principale est simple : si, dans un projet, vous avez réussi à bien configurer le travail de Copilot avec des rôles, des critics, du contexte et de la journalisation, cette structure ne doit pas rester uniquement dans votre tête. Elle doit être formalisée comme une couche d’ingénierie portable. Le framework a trois objectifs principaux. Le premier est de lancer un nouveau projet plus rapidement. Pour ne pas recréer à chaque fois les agents, le bootstrap, les fichiers de contexte, les instructions et les règles de review depuis zéro. Le deuxième est de rendre le processus répétable. Install, upgrade, remove, remplissage du context, cycle executor-critic et review doivent se dérouler selon des règles prédéfinies et documentées, plutôt que dépendre d’une implémentation particulière dans un projet donné. Le troisième est de séparer le commun du spécifique au projet. Ce qui doit être commun : lifecycle du framework, rôles, safety gates, trace logs et structure de fichiers. Ce qui doit rester propre au projet : stack, structure du dépôt, commandes de build et de test, règles de vérification manuelle et spécificités métier ou techniques. L’objectif de ForgentFramework est de fournir une manière claire d’assembler un système multi-agent dans un nouveau dépôt, de tout répartir dans les bons fichiers et de l’utiliser dans Copilot sous VS Code.

Architecture de ForgentFramework

Il vaut mieux regarder ForgentFramework non pas comme un arbre de dossiers, mais comme plusieurs circuits de travail.

1. Couche de règles et de templates

Vient d’abord la partie normative : la spécification et les règles de travail. On y décrit comment le système agentique doit être organisé, comment fonctionnent les rôles, comment sont structurés les critics, quels scénarios de lifecycle existent, comment se font install, upgrade et remove, comment la trace est tenue et où le système doit s’arrêter. À côté se trouvent les templates et les scripts de bootstrap. Ils servent à déployer rapidement dans le projet la structure initiale : fichiers de base, instructions, agents et artefacts de configuration. En termes simples : la spécification décrit les règles, et les templates aident à les matérialiser dans un dépôt concret.

2. Circuit bootstrap

La deuxième couche importante est celle des bootstrap agents. Ils sont nécessaires pour maintenir le framework lui-même : installation, mise à jour, suppression et remplissage initial des fichiers de contexte. Le processus ressemble à ceci :

topology intent ↓ PRE_DISCOVERY ↓ confirmation de l’inventory ↓ dry-run ↓ APPLY ↓ context bootstrap ↓ critic review

Cela rend l’installation du framework contrôlée. L’agent découvre la topology du projet, identifie les dépôts présents dans le workspace, montre le plan, puis déploie les fichiers nécessaires seulement après confirmation.

3. Circuit de travail projet

La troisième couche est celle des project agents. Ce sont les agents qui travailleront déjà avec le projet lui-même : backend, frontend, DevOps, QA, security, documentation, etc. Le rôle central ici est le project orchestrator. Il ne se contente pas de répondre à une question de l’utilisateur. Il mène votre tâche comme un processus :

comprendre l’objectif ↓ découper la tâche en étapes ↓ choisir l’executor ↓ recevoir le résultat ↓ l’envoyer au critic ↓ prendre en compte les remarques ↓ faire la vérification finale

Ainsi, la tâche commence à être résolue par un groupe d’agents. Elle devient un cycle contrôlé : plan, exécution, critique, correction, arrêt ou escalade.

4. Contexte, spécialisation et observabilité

La quatrième couche comprend tout ce qui empêche le système de sombrer dans le chaos. Elle inclut :

• PROJECT.md ;
• AGENTS.md ;
• llms.txt ;
• .github/copilot-instructions.md ;
• scoped instructions ;
• prompts ;
• skills ;
• fichiers de session ;
• fichiers de trace ;
• artefacts compliance/eval ;
• rubrics.

Ces fichiers ont des rôles différents. PROJECT.md et AGENTS.md décrivent le projet lui-même et sa structure. llms.txt aide à fournir au modèle un aperçu compact du projet. copilot-instructions.md fixe les règles générales de comportement. Les scoped instructions et les skills ajoutent des règles pour des zones, technologies ou tâches spécifiques. Les fichiers de session stockent la mémoire d’un lancement concret. Les traces permettent ensuite de comprendre ce que le système a réellement fait. En résumé : la spécification définit les règles, bootstrap les déploie dans le projet, les project agents travaillent selon ces règles, et le contexte avec les traces rendent le processus vérifiable. Cela se voit le mieux sur un scénario de bout en bout. Supposons qu’il existe un host repo avec ForgentFramework et un product repo avec une application réelle. Le host repo contient :

• spécification ;
• templates ;
• catalogue d’agents ;
• skills ;
• scoped instructions ;
• processus de bootstrap ;
• traces.

Le product repo contient :

• application ;
• fichier solution ;
• Dockerfile ;
• pipeline YAML ;
• scripts SQL ;
• tests ;
• instructions projet.

Le processus typique ressemble à ceci. D’abord, l’utilisateur décrit la topology du workspace : où se trouve le host repo, où se trouve le product repo, quels dépôts participent au travail. Ensuite, le bootstrap-orchestrator construit un plan. Il ne doit pas écrire de fichiers immédiatement. Puis le circuit bootstrap passe par discovery, confirme l’inventory, fait un dry-run et n’applique les changements qu’après un APPLY explicite. Après cela, le context bootstrap est lancé : le framework remplit ou complète AGENTS.md, PROJECT.md, llms.txt et d’autres fichiers de contexte. Ensuite, le critic vérifie que le lifecycle n’a pas été violé. Et seulement après cela, le project-orchestrator entre en jeu pour travailler sur une vraie tâche dans le product repo. Si le critic trouve un problème, les findings vont dans la session memory. Le passage suivant doit tenir compte de ce qui a déjà été trouvé et de ce qui n’a pas fonctionné. Toutes les étapes importantes sont écrites dans les traces. Si la tâche est bloquée, si les critères ne sont pas clairs ou si la limite d’itérations est atteinte, le processus doit se terminer non par un « je vais encore essayer » infini, mais par le statut NEEDS_HUMAN.

Comment les principes de l’article 16 sont implémentés dans ForgentFramework

Voyons maintenant comment les principes du 16e article se manifestent ici.

Plan-and-Execute

La planification existe immédiatement à deux niveaux. D’abord, le bootstrap-orchestrator construit le plan d’installation ou de mise à jour du framework. Puis le project-orchestrator construit le plan pour la tâche applicative. Ici, le plan est une partie obligatoire du processus. Le système explique d’abord ce qu’il va faire, puis passe seulement ensuite à l’exécution.

ReAct

Ici, ReAct ressemble à un cycle d’ingénierie normal :

regarder ↓ formuler une hypothèse ↓ faire une action ↓ vérifier le résultat ↓ décider l’étape suivante

Par exemple, à l’étape bootstrap, l’agent étudie d’abord la structure du workspace, puis fait l’inventory, montre ensuite le dry-run, applique les changements, puis lance la review. C’est la même chose dans le project work : l’agent ne doit pas immédiatement modifier massivement les fichiers. Il doit d’abord comprendre le contexte, nommer une hypothèse, faire une action ciblée et vérifier le résultat.

Critic isolation

Dans ForgentFramework, le critic existe non seulement pour un scénario, mais pour chaque grand type d’agent. Il y a un critic pour les opérations bootstrap, un critic pour le context fill, un critic pour les project executors et des rôles critic séparés pour différentes tâches de domaine. Par exemple, les changements DevOps doivent être vérifiés non pas par le même agent qui les a faits, mais par le critic associé. L’idée est simple : l’executor fait le travail, le critic vérifie le résultat séparément. L’isolation est obtenue par les règles de formulation de la tâche du critic. Il faut transmettre au critic non pas la logique interne de l’executor ni tout l’historique de son raisonnement, mais des données concrètes à vérifier :

• tâche initiale ;
• critères d’acceptation ;
• fichiers modifiés ou diff ;
• résultat du travail de l’executor ;
• commandes de vérification et leur sortie, si elles existent.

Avec une telle formulation, le critic ne continue pas à penser comme l’executor et ne défend pas sa solution. Il regarde le résultat de l’extérieur : est-il conforme à la tâche, les règles du framework ont-elles été respectées, manque-t-il des vérifications, y a-t-il des risques ou des blockers ? Autrement dit, critic isolation dans ForgentFramework est réalisée avant tout au niveau des instructions : le critic reçoit un rôle séparé, une tâche séparée et un format de vérification séparé. Grâce à cela, la review devient une phase autonome du processus, et non une autoévaluation de l’executor.

Rubric et critique formelle

Le critic ne doit pas simplement écrire « j’aime bien » ou « ça a l’air mauvais ». Une review a besoin d’une rubric. Par exemple :

• Blocker ;
• Warning ;
• Missing validation ;
• Rollback risk ;
• Security impact.

Dans ForgentFramework, ces vérifications sont déplacées dans un rubric-layer : prompts de critic et spécifications séparées pour la review. Cela rend le résultat plus prévisible. Par exemple, si PRE_DISCOVERY a été ignoré, c’est un blocker. Si l’install a écrit des fichiers avant APPLY, c’est une violation du lifecycle.

Reflexion

Si une tentative n’a pas fonctionné, il est important de ne pas recommencer la suivante à zéro. ForgentFramework utilise pour cela la session memory. Les findings du critic vont dans TASK_CONTEXT.md, et la tentative suivante doit prendre ce fichier en compte. Autrement dit, l’erreur devient un artefact du processus :

• lors de la tentative précédente, le critic a trouvé un problème ;
• elle est enregistrée dans le session context ;
• l’executor suivant doit en tenir compte.

Context engineering

Dans ForgentFramework, le contexte n’est pas empilé dans un seul énorme prompt. Il est divisé en plusieurs couches, et chaque couche sert une partie spécifique du travail. Le framework context contient les règles générales du framework lui-même : lifecycle, rôles, critic process, trace protocol, rubrics, install/upgrade/remove. Cette couche répond à la question : comment le système agentique doit-il fonctionner ? Le project context contient les informations sur le projet concret : stack, environnements, commandes build/test, CI/CD, contraintes et règles de vérification manuelle. Cette couche répond à la question : avec quel système travaillons-nous maintenant ? Le repo context est la carte du dépôt : où se trouvent backend, frontend, fichiers DevOps, documentation, generated files, quelles zones peuvent être modifiées et lesquelles ne doivent pas l’être. Cela est généralement décrit via AGENTS.md et llms.txt. Les scoped instructions et skills sont des règles locales et des playbooks chargés uniquement si nécessaire. Par exemple, des règles séparées pour Terraform, Dockerfile, code backend ou security review. Le session context est la mémoire d’un lancement concret : ce qui a déjà été essayé, ce que le critic a trouvé, quelles erreurs doivent être prises en compte à l’itération suivante. Ce n’est pas une carte permanente du projet, mais l’historique de la tâche courante. L’idée est simple : différents rôles ont besoin de contextes différents. Le bootstrap agent a besoin de la topology, de discovery et des règles d’installation. Le project-orchestrator a besoin de la carte du repo et des critères de la tâche. L’executor a besoin d’une subtask concrète et des fichiers nécessaires. Le critic a besoin de la tâche, des critères d’acceptation et du résultat, mais pas de tout l’historique du raisonnement de l’executor. Ainsi, le context engineering devient une transmission contrôlée de l’information : le bon contexte, au bon rôle, au bon moment.

Step logging et observability

Pour un travail sérieux, il ne suffit pas d’obtenir le résultat. Il faut aussi comprendre comment le système y est arrivé. ForgentFramework dispose de traces pour cela. La trace doit contenir les événements clés :

• discovery ;
• dry-run ;
• apply ;
• critic review ;
• executor result ;
• findings ;
• statut final.

Cela rend le processus agentique lisible. On peut revenir en arrière et voir exactement ce qui s’est passé, qui a fait quoi et à quelle étape le problème est apparu.

Stop and escalate

Le système ne doit pas tourner indéfiniment dans une boucle « je vais encore essayer ». ForgentFramework nécessite pour cela des règles d’arrêt explicites :

• limite d’itérations ;
• passage à NEEDS_HUMAN ;
• arrêt lorsque les acceptance criteria sont flous ;
• arrêt avant les changements dangereux ;
• fin de l’install uniquement après critic et context bootstrap.

C’est particulièrement important pour les tâches DevOps et d’infrastructure. Parfois, la bonne action de l’agent n’est pas de continuer, mais de dire honnêtement : « ici, il faut un humain ».

Least privilege

Tous les rôles n’ont pas besoin d’un accès complet. Le planner peut travailler en read-only. Le critic doit presque toujours être read-only. L’executor peut avoir le droit de modifier des fichiers, mais ne doit pas changer arbitrairement les artefacts du framework. Les bootstrap agents doivent s’occuper du framework lifecycle, et non du développement applicatif. Les project agents doivent travailler avec le product repo, mais ne doivent pas remplacer le circuit bootstrap. L’idée est simple : moins un rôle a de droits inutiles, plus son comportement est sûr et prévisible.

Comment utiliser ForgentFramework sur un nouveau projet

Si l’on décrit le usage flow depuis zéro, il ressemble à ceci. Il faut d’abord décider où vivra le framework. Il y a deux options. La première consiste à maintenir ForgentFramework comme host repo séparé et à le connecter au workspace à côté du product repo. La deuxième est l’approche vendored, où framework/ est placé directement à l’intérieur du repo cible. Après cela, il faut lancer le circuit bootstrap. Si le projet n’a pas encore de bootstrap agents, la structure de départ peut être déployée via les scripts bootstrap :

.\framework\tools\bootstrap.ps1

ou :

bash framework/tools/bootstrap.sh

Mais il est important de comprendre que ces scripts ne sont que la première étape technique. Ils déposent les fichiers de base et les agents. Le lifecycle complet d’installation doit ensuite passer par les bootstrap agents. Le point d’entrée principal est le bootstrap-orchestrator. C’est lui qui doit conduire les opérations :

• Install ;
• Upgrade ;
• Remove ;
• context bootstrap.

Ensuite, le processus suit ce parcours :

topology intent ↓ PRE_DISCOVERY ↓ confirmed inventory ↓ dry-run ↓ APPLY ↓ repo context bootstrap ↓ critic review ↓ project work

L’installation est considérée comme terminée non pas après la première écriture de fichiers, mais seulement après que la couche de contexte a été remplie et que le critic a confirmé que le lifecycle n’a pas été violé. Après cela, on peut passer au travail normal sur le projet via les Group 1 agents : project-orchestrator, domain executors et critics. Lorsque le projet commence à vivre, le framework est progressivement complété par des couches spécifiques au projet :

• scoped instructions ;
• domain skills ;
• critics spécifiques au repo ;
• prompts ;
• model mapping ;
• règles de validation manuelle.

Conclusion

ForgentFramework est ma tentative de rassembler au même endroit les pratiques qui ont commencé à se répéter dans presque chaque projet : rôles d’agents, passages critic, bootstrap, repo context, session memory, traces, rules, skills et points d’arrêt clairs.