Communitygithub.com

AgentPilotLab/loop-goal-runner

Compétence de mode objectif avec état pour Codex, Claude Code et agents IA, incluant mémoire STATE.md, portes et règles d'arrêt.

Qu'est-ce que loop-goal-runner ?

Cette compétence transforme une tâche ouverte de Codex en une boucle stateful avec un objectif clair, une mémoire persistante via `STATE.md`, une porte objective (gate) et une règle d'arrêt. Elle est utile pour les tâches qui se répètent ou nécessitent un suivi d'état entre les runs, comme les workflows d'ingénierie, de recherche ou de vérification. La compétence s'applique à Codex, Claude Code et d'autres agents IA disposant d'un système de description de compétences. Le workflow inclut un « Loop Fit Check » pour valider l'éligibilité de la tâche, la localisation ou la création d'un fichier d'état dédié, la rédaction d'un objectif mesurable, l'exécution d'une itération de boucle, et la décision d'utiliser des sous-agents ou des worktrees si nécessaire. Elle se termine par une notification claire avec l'état actuel, les preuves de vérification et la prochaine action recommandée.

Compatible avec✓Claude Code✓Codex CLI~Cursor
npx skills add AgentPilotLab/loop-goal-runner

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Loop Goal Runner

Utilisez cette compétence pour transformer une tâche ouverte de Codex en une petite boucle stateful. La boucle doit avoir un objectif clair, un état durable, une porte objective et une règle d'arrêt. Gardez le chemin par défaut léger ; n'ajoutez des sous-agents ou des worktrees que lorsque la tâche justifie le coût supplémentaire.

Contrat de base

Chaque exécution de boucle doit maintenir ces quatre artefacts ou décisions :

  1. Objectif : l'objectif actuel de l'utilisateur et les critères de complétion.
  2. État : un fichier STATE.md durable ou un système d'état externe explicitement nommé.
  3. Porte (Gate) : tests, lint, vérifications de type, build, validation de données, vérifications de captures d'écran, ou une autre commande de preuve objective.
  4. Règle d'arrêt : succès, blocage, tentatives maximales, durée d'exécution maximale, limite budgétaire, ou frontière d'approbation humaine.

Ne revendiquez pas la complétion sans preuve de vérification récente. S'il n'y a pas de porte objective, gardez le travail en mode conseil/manuel et indiquez que ce n'est pas un bon candidat pour une boucle.

Flux de travail

1. Effectuer le contrôle de validité de la boucle

Avant de construire ou de continuer une boucle, vérifiez si la tâche est adaptée :

  • Se répète au moins hebdomadairement, ou est assez longue pour que l'état persistant importe.
  • Dispose d'une porte objective capable de rejeter les mauvais résultats.
  • Peut être exécutée dans l'environnement disponible.
  • A une condition d'arrêt stricte.
  • Ne nécessite pas de jugement non supervisé pour l'architecture, l'authentification, les paiements, les déploiements de production ou les actions irréversibles.

Si l'une de ces conditions échoue, expliquez la condition échouée et utilisez un flux de travail normal en un coup, sauf si l'utilisateur demande explicitement de continuer.

2. Localiser ou créer l'état

Traitez l'état comme étant limité à l'objectif par défaut. Chaque objectif distinct doit avoir son propre fichier d'état durable, sauf si l'utilisateur demande explicitement de réutiliser un fichier d'état existant ou si le fichier existant appartient clairement au même objectif actif.

Ordre de priorité du chemin d'état :

  1. Utilisez le chemin exact du fichier d'état nommé par l'utilisateur, s'il existe.
  2. Si vous continuez un objectif existant et que son chemin d'état précédent est connu, réutilisez ce même fichier.
  3. Si l'objectif crée ou modifie principalement un référentiel de tâches ou un répertoire d'artefacts, utilisez le fichier STATE.md de la racine de cette tâche.
  4. Sinon, créez un fichier spécifique à l'objectif sous .codex/goals/<goal-slug>/STATE.md dans l'espace de travail actuel.
  5. Utilisez le fichier STATE.md de la racine de l'espace de travail uniquement lorsque l'espace de travail lui-même est l'objectif, ou lorsque l'utilisateur le sélectionne explicitement.

Avant de réutiliser un fichier STATE.md existant, inspectez ses sections Objectif et Statut actuel. Si elles décrivent un objectif différent, ne l'écrasez pas et ne le réutilisez pas. Créez plutôt un nouveau fichier d'état dédié à l'objectif et mentionnez brièvement la séparation.

Si le fichier d'état sélectionné n'existe pas et que les modifications de fichiers sont autorisées, créez-le à partir de references/state-template.md. Si les modifications ne sont pas autorisées, rédigez l'état initial dans la réponse et demandez à l'utilisateur de le placer.

Au début de chaque exécution de boucle :

  • Lisez le fichier d'état sélectionné et dédié à l'objectif avant de planifier.
  • Lisez le fichier AGENTS.md applicable le plus proche ou les instructions de projet équivalentes lorsqu'elles sont disponibles.
  • Extrayez la dernière exécution, le statut actuel, les blocages ouverts, les actions suivantes, l'historique de vérification, les leçons apprises et le chemin du fichier d'état.

À la fin de chaque exécution de boucle :

  • Mettez à jour uniquement le fichier d'état sélectionné et dédié à l'objectif avec les actions réelles effectuées.
  • Enregistrez les commandes de vérification et leurs résultats.
  • Enregistrez l'action suivante ou la raison d'arrêt.
  • Conservez les leçons qui devraient survivre à la compaction ou aux futures exécutions.
  • Ne déplacez, n'archivez ou ne réécrivez pas l'état d'un objectif non lié, sauf si l'utilisateur le demande explicitement.

3. Façonner l'objectif

Pour le mode Objectif de Codex, rédigez l'objectif de manière à ce qu'il soit mesurable :

/goal <objectif>. Fait quand : <la porte objective passe>. Contraintes : mettre à jour le fichier d'état sélectionné et dédié à l'objectif à chaque exécution ; s'arrêter après <N> tentatives échouées ou lorsque le jugement humain est nécessaire.

Si un objectif est déjà actif, utilisez l'objectif actuel comme source de vérité, sauf si l'utilisateur le modifie. Si aucun objectif n'est actif, déduisez un objectif de travail à partir de la demande de l'utilisateur et énoncez-le brièvement.

4. Exécuter une itération de boucle

Utilisez cette forme d'itération :

  1. Lire l'état et les instructions.
  2. Choisir la prochaine action utile la plus petite.
  3. Exécuter l'action.
  4. Exécuter la porte pertinente ou expliquer pourquoi elle ne peut pas être exécutée.
  5. Examiner le diff ou le résultat.
  6. Mettre à jour le fichier d'état sélectionné et dédié à l'objectif.
  7. Décider de continuer, d'arrêter ou d'escalader.

Gardez les modifications limitées. Préférez une exécution manuelle fiable avant de planifier l'automatisation.

5. Décider d'utiliser des sous-agents

Par défaut, utilisez un seul agent. N'utilisez des sous-agents que si au moins une des conditions suivantes s'applique :

  • Des investigations indépendantes peuvent être exécutées en parallèle.
  • Une répartition créateur/vérificateur réduirait matériellement le risque.
  • La tâche comporte plusieurs échecs, sous-systèmes ou documents non liés.
  • L'utilisateur demande explicitement des agents parallèles ou des sous-agents.

Lorsque vous utilisez des sous-agents, appliquez ces modèles :

  • Créateur/vérificateur : un agent implémente ou investigue, un autre révise la conformité aux spécifications et la qualité du code.
  • Répartition parallèle : un agent par domaine de problème indépendant.
  • Vérificateur : un nouvel agent examine les preuves, pas le raisonnement caché.

Ne traitez pas l'opinion d'un sous-agent comme une porte stricte. La vérification objective l'emporte toujours.

6. Décider d'utiliser des worktrees

Utilisez des worktrees pour les modifications de code lorsque plusieurs agents ou branches de longue durée peuvent écrire simultanément. Ignorez les worktrees pour la recherche en lecture seule, l'analyse de documents, les petites modifications d'un seul fichier ou les espaces de travail sans référentiel.

Si des worktrees sont nécessaires, privilégiez le support natif des worktrees de Codex lorsqu'il est disponible. Sinon, utilisez les worktrees Git uniquement après avoir confirmé le référentiel cible et vous être assuré que le répertoire du worktree ne sera pas accidentellement validé.

7. Complétion et escalade

Arrêtez-vous et signalez clairement lorsque :

  • La porte réussit et les critères d'objectif sont remplis.
  • Le nombre maximal de tentatives, la durée d'exécution ou la limite budgétaire est atteint.
  • Des autorisations, identifiants, services externes ou un jugement humain sont nécessaires.
  • Le même blocage se répète sur trois tours de boucle consécutifs.
  • La boucle devrait toucher à l'architecture, à l'authentification, aux paiements, aux déploiements de production, aux secrets ou aux autorisations étendues sans approbation humaine explicite.

La réponse finale doit inclure l'état actuel, les preuves de vérification et l'action recommandée suivante.

Fiabilité du déclenchement

Le déclenchement de la compétence est basé sur la description. Pour que cette compétence s'exécute automatiquement lors d'une future utilisation du mode Objectif, ajoutez l'extrait dans references/agents-snippet.md au fichier AGENTS.md global ou du projet.

Références

  • references/state-template.md : modèle pour les nouveaux fichiers STATE.md.
  • references/agents-snippet.md : instruction durable optionnelle pour que Codex invoque cette compétence chaque fois que l'utilisateur démarre ou discute d'un objectif.

Skills associés