jacklicn/agent-workflow

Création d'un Workflow

Un Workflow est une unité de processus réutilisable qui traduit « ce que l'utilisateur veut faire » en « quoi faire en premier, quoi ensuite, quel outil chaque étape utilise, et ce qu'elle produit ». Cette compétence vous guide depuis les besoins de l'utilisateur jusqu'à un fichier WORKFLOW.md conforme à la spécification docs/workflow/index.md.

Lisez la spécification avant de créer : docs/workflow/index.md (divulgation progressive à trois niveaux, correspondance graphe-étape un-à-un, règles de processus, conventions d'appel d'outils).

Quand l'utiliser

• L'utilisateur demande de « créer un workflow / processus / flux standardisé »
• L'utilisateur décrit une tâche en plusieurs étapes qu'il veut solidifier en un flux exécuté automatiquement
• L'utilisateur demande de modifier ou d'améliorer un workflow existant
• L'utilisateur a réalisé quelque chose de réutilisable et multi-étape dans la session et dit « solidifie ce flux »

Processus de Création

Phase 1 : Comprendre l'Intention

Interviewez d'abord ; ne vous précipitez pas à écrire des fichiers :

1. Quel problème résout-il ? Donnez un nom à la classe de tâche (ex. « revue de code », « notes de version »).
2. Scénario de déclenchement : quand l'utilisateur l'utilisera-t-il ? Collectez les mots déclencheurs (chinois + anglais).
3. Entrées et sorties : quelles entrées sont nécessaires (fichiers/répertoires/chaînes) ? Qu'est-ce qui est produit (fichiers/rapports) ?
4. Étapes existantes : l'utilisateur a-t-il déjà un flux habituel ? Extrayez les séquences d'appels d'outils, les corrections et les formats d'entrée/sortie de l'historique de la session.
5. Limites et règles : que ne faut-il pas faire ? Où vont les artefacts ? Comment les échecs sont-ils gérés ?

Complétez les informations manquantes avec ask_user avant de passer à la phase suivante.

Phase 2 : Concevoir le Diagramme de Flux

Dessinez le flux d'exécution avec mermaid, en respectant la règle de correspondance graphe-étape (spec 5.2.1) :

• Chaque nœud doit avoir une section d'étape correspondante ; chaque étape doit apparaître une fois dans le graphe
• Les noms des nœuds correspondent exactement aux noms des étapes et sont globalement uniques (le préfixe step-N n'a pas besoin d'apparaître dans les nœuds)
• Les nœuds de décision utilisent des losanges {}, doivent aussi avoir une section d'étape, et utilisent Branch pour indiquer où va chaque branche
• Les étapes parallèles (dispersion) sont un seul nœud dans le graphe
• Le graphe doit être complet : début, branches, fin

Montrez le graphe à l'utilisateur pour confirmation avant d'écrire les étapes.

Phase 3 : Écrire le WORKFLOW.md

Créez le répertoire et les fichiers sous <workspace>/workflows/<name>/ :

1. frontmatter (métadonnées de niveau 1) :
   • name : en kebab-case, correspondant au nom du répertoire, uniquement lettres minuscules/chiffres/tirets
   • description : fonction + moment d'utilisation + mots déclencheurs (chinois et anglais), détermine le taux de déclenchement
   • inputs / outputs : déclarez explicitement, marquez comme requis
   • version / tags : optionnels
2. Overview : un paragraphe indiquant ce qu'il fait, quand l'utiliser et ce qu'il produit
3. Flowchart : le graphe mermaid cohérent avec la Phase 2
4. Steps : une section ### <id>: <name> par étape, avec les attributs : Tools / Input / Depends on / Action / Check (les nœuds de décision ajoutent Branch, optionnellement when)
5. Process Rules : contraintes d'ordre, dépendances de données, portes de validation, contraintes d'effets secondaires, vérification d'état final
6. Tool Call Conventions : privilégiez les outils intégrés, scripts comme solution de repli, lisez plus écrivez moins, conventions de chemin

Divulgation progressive : mettez les longs tableaux dans REFERENCES.md, la logique déterministe dans scripts/, gardez le corps léger (<500 lignes).

Phase 4 : Auto-Vérification et Validation

Après avoir écrit, vérifiez par rapport à la spécification :

• Correspondance graphe-étape un-à-un : pas de nœud « orphelin » dans le graphe, pas d'étape « orpheline » dans les sections
• Noms des nœuds uniques et correspondant aux noms des étapes
• Chaque étape a une Check concrète et décidable (ex. « le fichier existe et n'est pas vide », pas « confirmer le succès »)
• Les noms d'outils sont précis (read_file / exec, pas « voir le fichier »)
• inputs / outputs cohérents avec les références des étapes
• Les règles couvrent la gestion des échecs (réessai / annulation / demander à l'utilisateur)
• La description du frontmatter inclut la fonction et les mots déclencheurs

Utilisez workflow_list pour confirmer que le nouveau workflow est découvert, et workflow_get <name> pour vérifier qu'il est lisible.

Phase 5 : Livrer

Informez l'utilisateur :

• Le nom et le chemin du workflow
• Le scénario de déclenchement (quelle formulation le déclenche)
• Un aperçu du flux (nombre d'étapes, décisions/parallélisme)
• Optionnel : suggérez 2-3 demandes de test réelles pour vérifier qu'il fonctionne

Modification d'un Workflow Existant

• Lisez d'abord le contenu actuel avec workflow_get <name>
• Gardez le name dans le frontmatter et le nom du répertoire inchangés
• Suivez la même spécification pour les modifications ; exécutez l'auto-vérification de la Phase 4 après l'édition

Notes

• Écrivez uniquement dans le workflows/ de l'espace de travail, ne modifiez jamais les workflows intégrés en lecture seule ; un workflow de l'espace de travail du même nom remplace l'intégré
• Un workflow résout une seule classe de tâche ; n'empilez pas de flux non liés
• Gardez les étapes entre 3 et 8 ; au-delà, divisez ou référencez un sous-workflow
• N'écrivez jamais d'instructions malveillantes ou trompeuses ; les règles doivent être auditable