Vue d’ensemble des workflows

Les workflows sont le mécanisme de CodeCourier pour orchestrer des pipelines d’agents IA multi-étapes. Au lieu d’envoyer un seul prompt à un seul agent, les workflows vous permettent de définir une séquence d’étapes d’agent - chacune avec son propre rôle, outil CLI, modèle et instructions - qui collaborent pour produire des résultats de meilleure qualité. Un workflow est un blueprint réutilisable ; chaque fois que vous l’exécutez, CodeCourier crée un run qui suit l’exécution à travers chaque étape.

Qu’est-ce qu’un workflow ?

Un workflow dans CodeCourier est un template qui définit comment les agents IA collaborent sur une tâche. Il spécifie :

• Quels agents participent - Chaque étape du pipeline correspond à une persona (une configuration d’agent nommée avec son propre outil CLI, modèle et instructions).
• Dans quel ordre ils s’exécutent - Les étapes s’exécutent séquentiellement. La sortie d’une étape devient le contexte de la suivante.
• Si un groupe d’étapes itère - Une paire designer+checker peut être placée à l’intérieur d’un Iteration Block afin que le groupe se répète jusqu’à ce que le checker approuve, dans la limite du plafond d’itérations du block. Les étapes en dehors d’un Iteration Block s’exécutent une fois.
• Quelle configuration de sandbox utiliser - Le workflow porte une config de sandbox par défaut (outil CLI, modèle, ressources) qui s’applique à toutes les étapes sauf surcharge.

Concepts fondamentaux

Blueprints vs. runs

Il existe une distinction cruciale entre un workflow et un run. Un workflow est un blueprint - il définit la structure du pipeline mais n’exécute rien. Un run est une instance d’exécution d’un workflow. Lorsque vous démarrez un workflow, CodeCourier crée un enregistrement de run qui suit l’état d’exécution, le prompt, la configuration et les résultats. Vous pouvez exécuter le même workflow de nombreuses fois, produisant plusieurs runs avec des prompts et configurations différents.

Pipelines de personas

Le système de workflow de CodeCourier utilise une architecture de pipeline de personas. Chaque étape du pipeline est liée à une persona - une identité d’agent préconfigurée avec un rôle spécifique (designer, checker, optimizer, prompter, investigator, evaluator, judge ou answerer), un outil CLI, un modèle et des instructions personnalisées. Cela signifie que vous contrôlez non seulement ce que fait l’agent, mais aussi comment il le fait.

Par exemple, un workflow de revue de code pourrait définir :

1. Une persona designer utilisant Claude Opus pour l’implémentation.
2. Une persona checker utilisant Claude Sonnet pour les tests E2E.
3. Une persona optimizer pour le nettoyage du code après approbation.

Iteration Blocks

L’itération est explicite et opt-in : elle vit à l’intérieur d’un nœud Iteration Block. Les étapes consécutives partageant le même loopId forment un block, et le block se répète comme une unité. Le pattern canonique est le block designer-checker :

1. Le designer implémente les changements demandés.
2. Le checker passe en revue l’implémentation et produit un verdict.
3. Si le checker passe, le block sort et le pipeline continue. Si le checker échoue, le designer reçoit le feedback du checker et le block se relance.

Chaque block a son propre plafond loopMaxIterations (3 par défaut) pour éviter les boucles infinies. Lorsque le plafond est atteint sans verdict de passage, le block se termine et le run est marqué comme échoué.

Les étapes en dehors d’un Iteration Block s’exécutent exactement une fois. Un checker qui n’est pas à l’intérieur d’un block émet toujours un verdict (persisté sur son run step) mais ne déclenche pasde retry automatique.

Execution Blocks

En coulisses, l’orchestrateur parse le pipeline en execution blocks. Chaque block est soit un block single (une ou plusieurs étapes qui s’exécutent une fois), soit un block loop(l’Iteration Block - un groupe loopId qui se répète).

Modes d’exécution

Les workflows peuvent être déclenchés de plusieurs manières, chacune adaptée à un cas d’usage différent :

• Runs directs - Une exécution unique déclenchée manuellement depuis la page de détail du workflow ou la page Runs. Le point d’entrée le plus courant pour les tâches ponctuelles.
• Sprint Chains - Une exécution par lot qui lance le même workflow plusieurs fois en séquence, une fois par sprint. Chaque sprint produit sa propre pull request. Les sprint chains sont idéales pour le travail de développement par phases où chaque phase s’appuie sur la précédente. La chaîne suit les URLs de PR par sprint et prend en charge la reprise depuis n’importe quel index de sprint si un sprint échoue.
• Recurring Tasks - Des exécutions planifiées qui se déclenchent automatiquement à une fréquence configurée (quotidienne, tous les deux jours, hebdomadaire, bihebdomadaire ou mensuelle). Chaque déclenchement crée un run standard avec la source scheduled. Les tâches récurrentes sont idéales pour les contrôles de qualité continus, les mises à jour de dépendances automatisées et autres workflows de maintenance qui doivent s’exécuter à une cadence régulière.
• Work Chains (pilotées par les issues) - Des runs séquentiels créés par les work chains de session d’issue. Chaque élément de la chaîne est une issue différente traitée à travers le même pipeline de workflow.

Quality Scoring

Chaque workflow run participe au système de quality scoring de CodeCourier. Lorsque le pipeline inclut une étape Evaluator, cette étape produit des scores de qualité structurés sur cinq dimensions :

• Correctness - L’implémentation répond-elle aux exigences ?
• Type Safety - Les types TypeScript sont-ils corrects et complets ?
• Code Style - Le code suit-il les conventions du projet ?
• Test Coverage - Les changements sont-ils couverts par des tests ?
• Completeness - L’implémentation est-elle entièrement terminée ?

Ces cinq scores de dimension sont combinés en un score composite (0 à 100). Chaque run suit aussi un qualityScore global dérivé de toutes les étapes Evaluator du pipeline. Les scores sont visibles dans la vue détaillée du run et dans le dashboard de Monitoring, permettant l’analyse des tendances dans le temps.

Configuration du workflow

Chaque workflow porte une configuration qui contrôle comment ses étapes s’exécutent :

• Nom et description - Un nom lisible par un humain et une description optionnelle pour le blueprint de workflow.
• Config de sandbox par défaut - La configuration de base pour toutes les sandboxes créées pendant les runs : template ID, timeout, mémoire, nombre de CPU, modèle designer et modèle checker.
• Étapes du pipeline de personas - Un tableau ordonné de références de persona. Les étapes qui appartiennent à un Iteration Block portent un loopId (et le loopMaxIterations du block) ; les étapes en dehors de tout block ne portent ni l’un ni l’autre et s’exécutent une fois.

Comment les workflows s’exécutent

Lorsqu’un workflow est déclenché, la séquence suivante se produit :

1. Création du run - Un enregistrement de run est créé dans la base de données avec le prompt, la configuration et une référence au blueprint de workflow.
2. Dispatch Trigger.dev - Une tâche de fond est envoyée à la file de tâches Trigger.dev. C’est l’orchestrateur de workflow qui gère toute l’exécution.
3. Exécution des étapes - L’orchestrateur traite chaque execution block séquentiellement. Pour chaque étape, il crée une sandbox E2B, met en place l’environnement, exécute l’agent IA et enregistre les résultats.
4. Gestion des verdicts - Pour les étapes checker, le verdict (pass/fail avec feedback) détermine si la boucle continue.
5. Achèvement du run - Lorsque toutes les étapes terminent, le statut du run est mis à jour vers completed. Si une étape échoue fatalement, le run est marqué comme failed.
6. Création de PR - Si le run a travaillé sur une branche Git, une pull request est créée automatiquement.

Relation avec les autres fonctionnalités

• Sandboxes - Chaque étape de workflow crée et utilise sa propre sandbox. Le cycle de vie de la sandbox est géré par l’exécuteur d’étape.
• Personas - Les étapes de workflow référencent des personas pour leur configuration d’agent. Modifier une persona met à jour tous les workflows qui l’utilisent.
• Issues - Les sessions d’issue peuvent découvrir des problèmes qui sont exécutés comme des workflow runs séquentiels via les work chains.
• Sprint Chains - Une exécution par lot qui lance le même workflow plusieurs fois, chaque sprint produisant sa propre PR.
• Recurring Tasks - Une automatisation planifiée qui déclenche le workflow à une fréquence configurée sans intervention manuelle.
• Learnings - Les learnings sont extraits des sandboxes de workflow run et réinjectés dans les runs futurs via des versions de learning compilées.
• Suivi d’usage - Chaque workflow run génère des enregistrements d’usage pour le temps de compute E2B, la consommation de tokens IA et le coût global.

Cas d’usage

• Cycles Design-Review - Un designer implémente des changements et un checker les vérifie avec des tests E2E, en bouclant jusqu’à ce que la qualité passe.
• Raffinement de prompt - Un agent prompter affine une description de tâche vague en un prompt détaillé avant de le transmettre à un designer.
• Investigation puis correction - Un investigator analyse la codebase pour comprendre l’issue, puis un designer implémente la correction sur la base de l’investigation.
• Génération de code multi-agents - Différents agents gèrent différents aspects (frontend, backend, testing) d’une fonctionnalité en séquence.
• Livraison à qualité contrôlée - Une étape evaluator note l’implémentation par rapport aux seuils de qualité avant que la PR ne soit ouverte, garantissant que seuls des changements prêts pour la production sont soumis à la revue.
• Développement par lots en phases - Les sprint chains lancent le même workflow à travers plusieurs phases d’un projet, chaque sprint livrant un ensemble de changements discret et révisable.
• Automatisation continue - Les tâches récurrentes déclenchent des workflows de qualité, de sécurité ou de dépendances selon un planning, gardant la codebase saine sans intervention manuelle.